fix(terminal): insert_before() now accepts lines > terminal height and doesn't add an extra blank line (#596 )

Fixes issue with inserting content with height>viewport_area.height and adds the ability to insert content of height>terminal_height - Adds TestBackend::append_lines() and TestBackend::clear_region() methods to support testing the changes
ci(codecov): adjust threshold and noise settings (#615 )
2023-11-08 10:04:35 -08:00 · 2023-11-05 10:21:11 +01:00 · 2023-10-25 14:01:04 -07:00 · 2023-10-25 02:44:36 -07:00 · 2023-10-23 04:06:53 -07:00 · 2023-10-23 04:04:26 -07:00
178 changed files with 35048 additions and 4892 deletions
--- a/.cargo-husky/hooks/pre-push
+++ b/.cargo-husky/hooks/pre-push
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+
+if !(command cargo-make >/dev/null 2>&1); then # Check if cargo-make is installed
+    echo Attempting to run cargo-make as part of the pre-push hook but it\'s not installed.
+    echo Please install it by running the following command:
+    echo
+    echo "    cargo install --force cargo-make"
+    echo
+    echo If you don\'t want to run cargo-make as part of the pre-push hook, you can run
+    echo the following command instead of git push:
+    echo
+    echo "    git push --no-verify"
+    exit 1
+fi
+
+cargo make ci
--- a/.cz.toml
+++ b/.cz.toml
@@ -0,0 +1,78 @@
+# configuration for https://github.com/commitizen/cz-cli
+
+[tool.commitizen]
+name = "cz_customize"
+tag_format = "$version"
+version_type = "semver"
+version_provider = "cargo"
+update_changelog_on_bump = true
+major_version_zero = true
+use_shortcuts = true
+
+[tool.commitizen.customize]
+message_template = """{{change_type}}({{scope}}): {{subject}}
+
+{% if body %}\
+{{body}}\
+{% endif %}
+
+{%if is_breaking_change %}\
+BREAKING_CHANGE: \
+{% endif %}\
+{{footer}}\
+"""
+example = "feature: this feature enable customize through config file"
+schema = "<type>(<scope>): <subject>\n\n<body>\n\n<footer>"
+schema_pattern = "(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)\\(\\w+\\):\\s(?P<subject>.*)(\\n\\n(?P<body>.*))?(\\n\\n(?P<footer>.*))?"
+
+# The order needs to be preserved, as it influences the order when executing cz commit/cz c
+
+# Change types
+[[tool.commitizen.customize.questions]]
+type = "list"
+name = "change_type"
+choices = [
+    { value = "build", name = "build: Changes that affect the build system or external dependencies (example scopes: pip, docker, npm)", key = "b" },
+    { value = "chore", name = "chore: A modification that generally does not fall into any other category", key = "c" },
+    { value = "ci", name = "ci: Changes to our CI configuration files and scripts (example scopes: GitLabCI)", key = "i" },
+    { value = "docs", name = "docs: Documentation only changes", key = "d" },
+    { value = "feat", name = "feat: A new feature.", key = "f" },
+    { value = "fix", name = "fix: A bug fix.", key = "x" },
+    { value = "perf", name = "perf: A code change that improves performance", key = "p" },
+    { value = "refactor", name = "refactor: A code change that neither fixes a bug nor adds a feature", key = "r" },
+    { value = "revert", name = "revert: Revert previous commits", key = "v" },
+    { value = "style", name = "style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)", key = "s" },
+    { value = "test", name = "test: Adding missing or correcting existing tests", key = "t" },
+]
+message = "Select the type of change you are committing"
+
+# The scope of the change, can be a file, class name or other context
+[[tool.commitizen.customize.questions]]
+type = "input"
+name = "scope"
+message = "What is the scope of this change? (class or file name): (press [enter] to skip)\n"
+
+# Summary of the changes
+[[tool.commitizen.customize.questions]]
+"type" = "input"
+"name" = "subject"
+"message" = "Write a short and imperative summary of the code changes: (lower case and no period)\n"
+
+# The commit body, elaborate the changes if need be.
+[[tool.commitizen.customize.questions]]
+type = "input"
+name = "body"
+message = "Provide additional contextual information about the code changes: (press [enter] to skip)\n"
+
+# Specify if the changes are breaking
+[[tool.commitizen.customize.questions]]
+type = "confirm"
+name = "is_breaking_change"
+message = "Is this a BREAKING CHANGE?"
+default = false
+
+# Reference closing issues and share other
+[[tool.commitizen.customize.questions]]
+type = "input"
+name = "footer"
+message = "Footer. Information about Breaking Changes and reference issues that this commit closes: (press [enter] to skip)"
--- a/.editorconfig
+++ b/.editorconfig
@@ -0,0 +1,11 @@
+# configuration for https://editorconfig.org
+
+root = true
+
+[*.rs]
+indent_style = space
+indent_size = 4
+
+[*.yml]
+indent_style = space
+indent_size = 2
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -0,0 +1,8 @@
+# See https://help.github.com/articles/about-codeowners/
+# for more info about CODEOWNERS file
+
+# It uses the same pattern rule for gitignore file
+# https://git-scm.com/docs/gitignore#_pattern_format
+
+# Maintainers
+* @orhun @mindoodoo @sayanarijit @joshka @kdheepak
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,60 @@
+---
+name: Bug report
+about: Create an issue about a bug you encountered
+title: ''
+labels: bug
+assignees: ''
+---
+
+<!--
+Hi there, sorry `ratatui` is not working as expected.
+Please fill this bug report conscientiously.
+A detailed and complete issue is more likely to be processed quickly.
+-->
+
+## Description
+<!--
+A clear and concise description of what the bug is.
+-->
+
+
+## To Reproduce
+<!--
+Try to reduce the issue to a simple code sample exhibiting the problem.
+Ideally, fork the project and add a test or an example.
+-->
+
+
+## Expected behavior
+<!--
+A clear and concise description of what you expected to happen.
+-->
+
+
+## Screenshots
+<!--
+If applicable, add screenshots, gifs or videos to help explain your problem.
+-->
+
+
+## Environment
+<!--
+Add a description of the systems where you are observing the issue. For example:
+- OS: Linux
+- Terminal Emulator: xterm
+- Font: Inconsolata (Patched)
+- Crate version: 0.7
+- Backend: termion
+-->
+
+- OS:
+- Terminal Emulator:
+- Font:
+- Crate version:
+- Backend:
+
+## Additional context
+<!--
+Add any other context about the problem here.
+If you already looked into the issue, include all the leads you have explored.
+-->
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Discord Chat
+    url: https://discord.gg/pMCEU9hNEj
+    about: Ask questions about ratatui on Discord
+  - name: Matrix Chat
+    url: https://matrix.to/#/#ratatui:matrix.org
+    about: Ask questions about ratatui on Matrix
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,32 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+## Problem
+<!--
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+-->
+
+## Solution
+<!--
+A clear and concise description of what you want to happen.
+Things to consider:
+- backward compatibility
+- ease of use of the API (https://rust-lang.github.io/api-guidelines/)
+- consistency with the rest of the crate
+-->
+
+## Alternatives
+<!--
+A clear and concise description of any alternative solutions or features you've considered.
+-->
+
+## Additional context
+<!--
+Add any other context or screenshots about the feature request here.
+-->
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -0,0 +1,18 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  # Maintain dependencies for Cargo
+  - package-ecosystem: "cargo"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -0,0 +1 @@
+<!-- Please read CONTRIBUTING.md before submitting any pull request. -->
--- a/.github/workflows/cd.yml
+++ b/.github/workflows/cd.yml
@@ -0,0 +1,86 @@
+name: Continuous Deployment
+
+on:
+  workflow_dispatch:
+  schedule:
+    # At 00:00 on Saturday
+    # https://crontab.guru/#0_0_*_*_6
+    - cron: "0 0 * * 6"
+  push:
+    tags:
+      - "v*.*.*"
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  publish-alpha:
+    name: Create an alpha release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    if: ${{ !startsWith(github.event.ref, 'refs/tags/v') }}
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Calculate the next release
+        run: |
+          suffix="alpha"
+          last_tag="$(git tag --sort=committerdate | tail -1)"
+          if [[ "${last_tag}" = *"-${suffix}"* ]]; then
+            # increment the alpha version
+            # e.g. v0.22.1-alpha.12 -> v0.22.1-alpha.13
+            alpha="${last_tag##*-${suffix}.}"
+            next_alpha="$((alpha + 1))"
+            next_tag="${last_tag/%${alpha}/${next_alpha}}"
+          else
+            # increment the patch and start the alpha version from 0
+            # e.g. v0.22.0 -> v0.22.1-alpha.0
+            patch="${last_tag##*.}"
+            next_patch="$((patch + 1))"
+            next_tag="${last_tag/%${patch}/${next_patch}}-${suffix}.0"
+          fi
+          # update the crate version
+          msg="# crate version"
+          sed -E -i "s/^version = .* ${msg}$/version = \"${next_tag#v}\" ${msg}/" Cargo.toml
+          echo "NEXT_TAG=${next_tag}" >> $GITHUB_ENV
+          echo "Next alpha release: ${next_tag} 🐭"
+
+      - name: Publish on crates.io
+        uses: actions-rs/cargo@v1
+        with:
+          command: publish
+          args: --allow-dirty --token ${{ secrets.CARGO_TOKEN }}
+
+      - name: Generate a changelog
+        uses: orhun/git-cliff-action@v2
+        with:
+          config: cliff.toml
+          args: --unreleased --tag ${{ env.NEXT_TAG }} --strip header
+        env:
+          OUTPUT: BODY.md
+
+      - name: Publish on GitHub
+        uses: ncipollo/release-action@v1
+        with:
+          tag: ${{ env.NEXT_TAG }}
+          prerelease: true
+          bodyFile: BODY.md
+
+  publish-stable:
+    name: Create a stable release
+    runs-on: ubuntu-latest
+    if: ${{ startsWith(github.event.ref, 'refs/tags/v') }}
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+
+      - name: Publish on crates.io
+        uses: actions-rs/cargo@v1
+        with:
+          command: publish
+          args: --token ${{ secrets.CARGO_TOKEN }}
--- a/.github/workflows/check-pr.yml
+++ b/.github/workflows/check-pr.yml
@@ -0,0 +1,83 @@
+name: Check Pull Requests
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - synchronize
+      - labeled
+      - unlabeled
+  merge_group:
+
+permissions:
+  pull-requests: write
+
+jobs:
+  check-title:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check PR title
+        if: github.event_name == 'pull_request_target'
+        uses: amannn/action-semantic-pull-request@v5
+        id: check_pr_title
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      # Add comment indicating we require pull request titles to follow conventional commits specification
+      - uses: marocchino/sticky-pull-request-comment@v2
+        if: always() && (steps.check_pr_title.outputs.error_message != null)
+        with:
+          header: pr-title-lint-error
+          message: |
+            Thank you for opening this pull request!
+
+            We require pull request titles to follow the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/) and it looks like your proposed title needs to be adjusted.
+
+            Details:
+
+            > ${{ steps.check_pr_title.outputs.error_message }}
+
+      # Delete a previous comment when the issue has been resolved
+      - if: ${{ steps.check_pr_title.outputs.error_message == null }}
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: pr-title-lint-error
+          delete: true
+
+  check-breaking-change-label:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Check breaking change label
+      id: check_breaking_change
+      run: |
+        pattern='^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\(\w+\))?!:'
+        # Check if pattern matches
+        if echo "${{ github.event.pull_request.title }}" | grep -qE "$pattern"; then
+          echo "breaking_change=true" >> $GITHUB_OUTPUT
+        else
+          echo "breaking_change=false" >> $GITHUB_OUTPUT
+        fi
+    - name: Add label
+      if: steps.check_breaking_change.outputs.breaking_change == 'true'
+      uses: actions/github-script@v6
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        script: |
+          github.rest.issues.addLabels({
+            issue_number: context.issue.number,
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            labels: ['breaking change']
+          })
+
+  do-not-merge:
+    if: ${{ contains(github.event.*.labels.*.name, 'do not merge') }}
+    name: Prevent Merging
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check for label
+        run: |
+          echo "Pull request is labeled as 'do not merge'"
+          echo "This workflow fails so that the pull request cannot be merged"
+          exit 1
+
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,157 @@
+name: Continuous Integration
+
+on:
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  merge_group:
+
+# ensure that the workflow is only triggered once per PR,  subsequent pushes to the PR will cancel
+# and restart the workflow. See https://docs.github.com/en/actions/using-jobs/using-concurrency
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+env:
+  # don't install husky hooks during CI as they are only needed for for pre-push
+  CARGO_HUSKY_DONT_INSTALL_HOOKS: true
+
+# lint, clippy and coveraget jobs are intentionally early in the workflow to catch simple
+# formatting, typos, and missing tests as early as possible. This allows us to fix these and
+# resubmit the PR without having to wait for the comprehensive matrix of tests to complete.
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        if: github.event_name != 'pull_request'
+        uses: actions/checkout@v4
+      - name: Checkout
+        if: github.event_name == 'pull_request'
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+      - name: Install Rust nightly
+        uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: rustfmt
+      - name: Install cargo-make
+        uses: taiki-e/install-action@cargo-make
+      - name: Check formatting
+        run: cargo make lint-format
+      - name: Check documentation
+        run: cargo make lint-docs
+      - name: Check conventional commits
+        uses: crate-ci/committed@master
+        with:
+          args: "-vv"
+          commits: HEAD
+      - name: Check typos
+        uses: crate-ci/typos@master
+      - name: Lint dependencies
+        uses: EmbarkStudios/cargo-deny-action@v1
+
+  clippy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - name: Install cargo-make
+        uses: taiki-e/install-action@cargo-make
+      - name: Run cargo make clippy-all
+        run: cargo make clippy
+
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: llvm-tools
+      - name: Install cargo-llvm-cov and cargo-make
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-llvm-cov,cargo-make
+      - name: Generate coverage
+        run: cargo make coverage
+      - name: Upload to codecov.io
+        uses: codecov/codecov-action@v3
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: true
+
+  check:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-latest, windows-latest, macos-latest ]
+        toolchain: [ "1.70.0", "stable" ]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install Rust {{ matrix.toolchain }}
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ matrix.toolchain }}
+      - name: Install cargo-make
+        uses: taiki-e/install-action@cargo-make
+      - name: Run cargo make check
+        run: cargo make check
+        env:
+          RUST_BACKTRACE: full
+
+  test-doc:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-latest, windows-latest, macos-latest ]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+      - name: Install cargo-make
+        uses: taiki-e/install-action@cargo-make
+      - name: Test docs
+        run: cargo make test-doc
+        env:
+          RUST_BACKTRACE: full
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-latest, windows-latest, macos-latest ]
+        toolchain: [ "1.70.0", "stable" ]
+        backend: [ crossterm, termion, termwiz ]
+        exclude:
+          # termion is not supported on windows
+          - os: windows-latest
+            backend: termion
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install Rust ${{ matrix.toolchain }}}
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ matrix.toolchain }}
+      - name: Install cargo-make
+        uses: taiki-e/install-action@cargo-make
+      - name: Test ${{ matrix.backend }}
+        run: cargo make test-backend ${{ matrix.backend }}
+        env:
+          RUST_BACKTRACE: full
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,4 @@ Cargo.lock
 *.log
 *.rs.rustfmt
 .gdb_history
+.idea/
--- a/.markdownlint.yaml
+++ b/.markdownlint.yaml
@@ -0,0 +1,15 @@
+# configuration for https://github.com/DavidAnson/markdownlint
+
+first-line-heading: false
+no-inline-html:
+  allowed_elements:
+    - img
+    - details
+    - summary
+    - div
+    - br
+line-length:
+  line_length: 100
+
+# to support repeated headers in the changelog
+no-duplicate-heading: false
--- a/.travis.yml
+++ b/.travis.yml
@@ -1,21 +0,0 @@
-language: rust
-
-rust:
-  - stable
-  - beta
-  - nightly
-
-cache: cargo
-
-matrix:
-  fast_finish: true
-  allow_failures:
-    - rust: nightly
-
-before_script:
-  - rustup component add rustfmt-preview
-
-script:
-  - if [ "$TRAVIS_RUST_VERSION" == "stable" ]; then make fmt; fi
-  - make build
-  - make test
--- a/BREAKING-CHANGES.md
+++ b/BREAKING-CHANGES.md
@@ -0,0 +1,226 @@
+# Breaking Changes
+
+This document contains a list of breaking changes in each version and some notes to help migrate
+between versions. It is compile manually from the commit history and changelog. We also tag PRs on
+github with a [breaking change] label.
+
+[breaking change]: (https://github.com/ratatui-org/ratatui/issues?q=label%3A%22breaking+change%22)
+
+## Summary
+
+This is a quick summary of the sections below:
+
+- [v0.24.0](#v0240)
+  - MSRV is now 1.70.0
+  - `ScrollbarState`: `position`, `content_length`, and `viewport_content_length` are now `usize`
+  - `BorderType`: `line_symbols` is now `border_symbols` and returns `symbols::border::set`
+  - `Frame<'a, B: Backend>` is now `Frame<'a>`
+  - `Stylize` shorthands for `String` now consume the value and return `Span<'static>`
+  - `Spans` is removed
+- [v0.23.0](#v0230)
+  - `Scrollbar`: `track_symbol` now takes `Option<&str>`
+  - `Scrollbar`: symbols moved to `symbols` module
+  - MSRV is now 1.67.0
+- [v0.22.0](#v0220)
+  - serde representation of `Borders` and `Modifiers` has changed
+- [v0.21.0](#v0210)
+  - MSRV is now 1.65.0
+  - `terminal::ViewPort` is now an enum
+  - `"".as_ref()` must be annotated to implement `Into<Text<'a>>`
+  - `Marker::Block` renders as a block char instead of a bar char
+- [v0.20.0](#v0200)
+  - MSRV is now 1.63.0
+  - `List` no longer ignores empty strings
+
+## [v0.24.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.24.0)
+
+### ScrollbarState field type changed from `u16` to `usize` ([#456])
+
+[#456]: https://github.com/ratatui-org/ratatui/pull/456
+
+In order to support larger content lengths, the `position`, `content_length` and
+`viewport_content_length` methods on `ScrollbarState` now take `usize` instead of `u16`
+
+### `BorderType::line_symbols` renamed to `border_symbols` ([#529])
+
+[#529]: https://github.com/ratatui-org/ratatui/issues/529
+
+Applications can now set custom borders on a `Block` by calling `border_set()`. The
+`BorderType::line_symbols()` is renamed to `border_symbols()` and now returns a new struct
+`symbols::border::Set`. E.g.:
+
+```rust
+let line_set: symbols::line::Set = BorderType::line_symbols(BorderType::Plain);
+// becomes
+let border_set: symbols::border::Set = BorderType::border_symbols(BorderType::Plain);
+```
+
+### Generic `Backend` parameter removed from `Frame` ([#530])
+
+[#530]: https://github.com/ratatui-org/ratatui/issues/530
+
+`Frame` is no longer generic over Backend. Code that accepted `Frame<Backend>` will now need to
+accept `Frame`. To migrate existing code, remove any generic parameters from code that uses an
+instance of a Frame. E.g.:
+
+```rust
+fn ui<B: Backend>(frame: &mut Frame<B>) { ... }
+// becomes
+fn ui(frame: Frame) { ... }
+```
+
+### `Stylize` shorthands now consume rather than borrow `String` ([#466])
+
+[#466]: https://github.com/ratatui-org/ratatui/issues/466
+
+In order to support using `Stylize` shorthands (e.g. `"foo".red()`) on temporary `String` values, a
+new implementation of `Stylize` was added that returns a `Span<'static>`. This causes the value to
+be consumed rather than borrowed. Existing code that expects to use the string after a call will no
+longer compile. E.g.
+
+```rust
+let s = String::new("foo");
+let span1 = s.red();
+let span2 = s.blue(); // will no longer compile as s is consumed by the previous line
+// becomes
+let span1 = s.clone().red();
+let span2 = s.blue();
+```
+
+### Deprecated `Spans` type removed (replaced with `Line`) ([#426])
+
+[#426]: https://github.com/ratatui-org/ratatui/issues/426
+
+`Spans` was replaced with `Line` in 0.21.0. `Buffer::set_spans` was replaced with
+`Buffer::set_line`.
+
+```rust
+let spans = Spans::from(some_string_str_span_or_vec_span);
+buffer.set_spans(0, 0, spans, 10);
+// becomes
+let line - Line::from(some_string_str_span_or_vec_span);
+buffer.set_line(0, 0, line, 10);
+```
+
+## [v0.23.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.23.0)
+
+### `Scrollbar::track_symbol()` now takes an `Option<&str>` instead of `&str` ([#360])
+
+[#360]: https://github.com/ratatui-org/ratatui/issues/360
+
+The track symbol of `Scrollbar` is now optional, this method now takes an optional value.
+
+```rust
+let scrollbar = Scrollbar::default().track_symbol("|");
+// becomes
+let scrollbar = Scrollbar::default().track_symbol(Some("|"));
+```
+
+### `Scrollbar` symbols moved to `symbols::scrollbar` and `widgets::scrollbar` module is private ([#330])
+
+[#330]: https://github.com/ratatui-org/ratatui/issues/330
+
+The symbols for defining scrollbars have been moved to the `symbols` module from the
+`widgets::scrollbar` module which is no longer public. To update your code update any imports to the
+new module locations. E.g.:
+
+```rust
+use ratatui::{widgets::scrollbar::{Scrollbar, Set}};
+// becomes
+use ratatui::{widgets::Scrollbar, symbols::scrollbar::Set} 
+```
+
+### MSRV updated to 1.67 ([#361])
+
+[#361]: https://github.com/ratatui-org/ratatui/issues/361
+
+The MSRV of ratatui is now 1.67 due to an MSRV update in a dependency (`time`).
+
+## [v0.22.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.22.0)
+
+### bitflags updated to 2.3 ([#205])
+
+[#205]: https://github.com/ratatui-org/ratatui/issues/205
+
+The serde representation of bitflags has changed. Any existing serialized types that have Borders or
+Modifiers will need to be re-serialized. This is documented in the [bitflags
+changelog](https://github.com/bitflags/bitflags/blob/main/CHANGELOG.md#200-rc2)..
+
+## [v0.21.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.21.0)
+
+### MSRV is 1.65.0  ([#171])
+
+[#171]: https://github.com/ratatui-org/ratatui/issues/171
+
+The minimum supported rust version is now 1.65.0.
+
+### `Terminal::with_options()` stabilized to allow configuring the viewport ([#114])
+
+[#114]: https://github.com/ratatui-org/ratatui/issues/114
+
+In order to support inline viewports, the unstable method `Terminal::with_options()` was stabilized
+and  `ViewPort` was changed from a struct to an enum.
+
+```rust
+let terminal = Terminal::with_options(backend, TerminalOptions {
+    viewport: Viewport::fixed(area),
+});
+// becomes
+let terminal = Terminal::with_options(backend, TerminalOptions {
+    viewport: Viewport::Fixed(area),
+});
+```
+
+### Code that binds `Into<Text<'a>>` now requires type annotations ([#168])
+
+[#168]: https://github.com/ratatui-org/ratatui/issues/168
+
+A new type `Masked` was introduced that implements `From<Text<'a>>`. This causes any code that did
+previously did not need to use type annotations to fail to compile.  To fix this, annotate or call
+to_string() / to_owned() / as_str() on the value. E.g.:
+
+```rust
+let paragraph = Paragraph::new("".as_ref());
+// becomes
+let paragraph = Paragraph::new("".as_str());
+```
+
+### `Marker::Block` now renders as a block rather than a bar character ([#133])
+
+[#133]: https://github.com/ratatui-org/ratatui/issues/133
+
+Code using the `Block` marker that previously rendered using a half block character (`'▀'``) now
+renders using the full block character (`'█'`). A new marker variant`Bar` is introduced to replace
+the existing code.
+
+```rust
+let canvas = Canvas::default().marker(Marker::Block);
+// becomes
+let canvas = Canvas::default().marker(Marker::Bar);
+```
+
+## [v0.20.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.20.0)
+
+v0.20.0 was the first release of Ratatui - versions prior to this were release as tui-rs. See the
+[Changelog](./CHANGELOG.md) for more details.
+
+### MSRV is update to 1.63.0 ([#80])
+
+[#80]: https://github.com/ratatui-org/ratatui/issues/80
+
+The minimum supported rust version is 1.63.0
+
+### List no longer ignores empty string in items ([#42])
+
+[#42]: https://github.com/ratatui-org/ratatui/issues/42
+
+The following code now renders 3 items instead of 2. Code which relies on the previous behavior will
+need to manually filter empty items prior to display.
+
+```rust
+let items = vec![
+    ListItem::new("line one"),
+    ListItem::new(""),
+    ListItem::new("line four"),
+];
+```
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,215 @@
+# Contribution guidelines
+
+First off, thank you for considering contributing to Ratatui.
+
+If your contribution is not straightforward, please first discuss the change you wish to make by
+creating a new issue before making the change, or starting a discussion on
+[discord](https://discord.gg/pMCEU9hNEj).
+
+## Reporting issues
+
+Before reporting an issue on the [issue tracker](https://github.com/ratatui-org/ratatui/issues),
+please check that it has not already been reported by searching for some related keywords. Please
+also check [`tui-rs` issues](https://github.com/fdehau/tui-rs/issues/) and link any related issues
+found.
+
+## Pull requests
+
+All contributions are obviously welcome. Please include as many details as possible in your PR
+description to help the reviewer (follow the provided template). Make sure to highlight changes
+which may need additional attention or you are uncertain about. Any idea with a large scale impact
+on the crate or its users should ideally be discussed in a "Feature Request" issue beforehand.
+
+### Keep PRs small, intentional and focused
+
+Try to do one pull request per change. The time taken to review a PR grows exponential with the size
+of the change. Small focused PRs will generally be much more faster to review. PRs that include both
+refactoring (or reformatting) with actual changes are more difficult to review as every line of the
+change becomes a place where a bug may have been introduced. Consider splitting refactoring /
+reformatting changes into a separate PR from those that make a behavioral change, as the tests help
+guarantee that the behavior is unchanged.
+
+### Code formatting
+
+Run `cargo make format` before committing to ensure that code is consistently formatted with
+rustfmt. Configuration is in [rustfmt.toml](./rustfmt.toml).
+
+### Search `tui-rs` for similar work
+
+The original fork of Ratatui, [`tui-rs`](https://github.com/fdehau/tui-rs/), has a large amount of
+history of the project. Please search, read, link, and summarize any relevant
+[issues](https://github.com/fdehau/tui-rs/issues/),
+[discussions](https://github.com/fdehau/tui-rs/discussions/) and [pull
+requests](https://github.com/fdehau/tui-rs/pulls).
+
+### Use conventional commits
+
+We use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) and check for them as
+a lint build step. To help adhere to the format, we recommend to install
+[Commitizen](https://commitizen-tools.github.io/commitizen/). By using this tool you automatically
+follow the configuration defined in [.cz.toml](.cz.toml). Your commit messages should have enough
+information to help someone reading the [CHANGELOG](./CHANGELOG.md) understand what is new just from
+the title. The summary helps expand on that to provide information that helps provide more context,
+describes the nature of the problem that the commit is solving and any unintuitive effects of the
+change. It's rare that code changes can easily communicate intent, so make sure this is clearly
+documented.
+
+### Clean up your commits
+
+The final version of your PR that will be committed to the repository should be rebased and tested
+against main. Every commit will end up as a line in the changelog, so please squash commits that are
+only formatting or incremental fixes to things brought up as part of the PR review. Aim for a single
+commit (unless there is a strong reason to stack the commits). See [Git Best Practices - On Sausage
+Making](https://sethrobertson.github.io/GitBestPractices/#sausage) for more on this.
+
+### Run CI tests before pushing a PR
+
+We're using [cargo-husky](https://github.com/rhysd/cargo-husky) to automatically run git hooks,
+which will run `cargo make ci` before each push. To initialize the hook  run `cargo test`. If
+`cargo-make` is not installed, it will provide instructions to install it for you. This will ensure
+that your code is formatted, compiles and passes all tests before you push. If you need to skip this
+check, you can use `git push --no-verify`.
+
+### Sign your commits
+
+We use commit signature verification, which will block commits from being merged via the UI unless
+they are signed. To set up your machine to sign commits, see [managing commit signature
+verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification)
+in GitHub docs.
+
+## Implementation Guidelines
+
+### Setup
+
+Clone the repo and build it using [cargo-make](https://sagiegurari.github.io/cargo-make/)
+
+Ratatui is an ordinary Rust project where common tasks are managed with
+[cargo-make](https://github.com/sagiegurari/cargo-make/). It wraps common `cargo` commands with sane
+defaults depending on your platform of choice. Building the project should be as easy as running
+`cargo make build`.
+
+```shell
+git clone https://github.com/ratatui-org/ratatui.git
+cd ratatui
+cargo make build
+```
+
+### Tests
+
+The [test coverage](https://app.codecov.io/gh/ratatui-org/ratatui) of the crate is reasonably
+good, but this can always be improved. Focus on keeping the tests simple and obvious and write unit
+tests for all new or modified code. Beside the usual doc and unit tests, one of the most valuable
+test you can write for Ratatui is a test against the `TestBackend`. It allows you to assert the
+content of the output buffer that would have been flushed to the terminal after a given draw call.
+See `widgets_block_renders` in [tests/widgets_block.rs](./tests/widget_block.rs) for an example.
+
+When writing tests, generally prefer to write unit tests and doc tests directly in the code file
+being tested rather than integration tests in the `tests/` folder.
+
+If an area that you're making a change in is not tested, write tests to characterize the existing
+behavior before changing it. This helps ensure that we don't introduce bugs to existing software
+using Ratatui (and helps make it easy to migrate apps still using `tui-rs`).
+
+For coverage, we have two [bacon](https://dystroy.org/bacon/) jobs (one for all tests, and one for
+unit tests, keyboard shortcuts `v` and `u` respectively) that run
+[cargo-llvm-cov](https://github.com/taiki-e/cargo-llvm-cov) to report the coverage. Several plugins
+exist to show coverage directly in your editor. E.g.:
+
+- <https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters>
+- <https://github.com/alepez/vim-llvmcov>
+
+### Documentation
+
+Here are some guidelines for writing documentation in Ratatui.  
+Every public API **must** be documented.
+
+Keep in mind that Ratatui tends to attract beginner Rust users that may not be familiar with Rust
+concepts.
+
+#### Content
+
+The main doc comment should talk about the general features that the widget supports and introduce
+the concepts pointing to the various methods. Focus on interaction with various features and giving
+enough information that helps understand why you might want something.
+
+Examples should help users understand a particular usage, not test a feature. They should be as
+simple as possible.  
+Prefer hiding imports and using wildcards to keep things concise. Some imports may still be shown
+to demonstrate a particular non-obvious import (e.g. `Stylize` trait to use style methods).  
+Speaking of `Stylize`, you should use it over the more verbose style setters:
+
+```rust
+let style = Style::new().red().bold();
+// not
+let style = Style::default().fg(Color::Red).add_modifier(Modifiers::BOLD);
+```
+
+#### Format
+
+- First line is summary, second is blank, third onward is more detail  
+
+```rust
+/// Summary
+///
+/// A detailed description
+/// with examples.
+fn foo() {}
+```
+
+- Max line length is 100 characters  
+See [vscode rewrap extension](https://marketplace.visualstudio.com/items?itemName=stkb.rewrap)
+
+- Doc comments are above macros  
+i.e.
+
+```rust
+/// doc comment
+#[derive(Debug)]
+struct Foo {}
+```
+
+- Code items should be between backticks  
+i.e. ``[`Block`]``, **NOT** ``[Block]``
+
+### Use of unsafe for optimization purposes
+
+We don't currently use any unsafe code in Ratatui, and would like to keep it that way. However there
+may be specific cases that this becomes necessary in order to avoid slowness. Please see [this
+discussion](https://github.com/ratatui-org/ratatui/discussions/66) for more about the decision.
+
+## Continuous Integration
+
+We use Github Actions for the CI where we perform the following checks:
+
+- The code should compile on `stable` and the Minimum Supported Rust Version (MSRV).
+- The tests (docs, lib, tests and examples) should pass.
+- The code should conform to the default format enforced by `rustfmt`.
+- The code should not contain common style issues `clippy`.
+
+You can also check most of those things yourself locally using `cargo make ci` which will offer you
+a shorter feedback loop than pushing to github.
+
+## Relationship with `tui-rs`
+
+This project was forked from [`tui-rs`](https://github.com/fdehau/tui-rs/) in February 2023, with the
+[blessing of the original author](https://github.com/fdehau/tui-rs/issues/654), Florian Dehau
+([@fdehau](https://github.com/fdehau)).
+
+The original repository contains all the issues, PRs and discussion that were raised originally, and
+it is useful to refer to when contributing code, documentation, or issues with Ratatui.
+
+We imported all the PRs from the original repository and implemented many of the smaller ones and
+made notes on the leftovers. These are marked as draft PRs and labelled as [imported from
+tui](https://github.com/ratatui-org/ratatui/pulls?q=is%3Apr+is%3Aopen+label%3A%22imported+from+tui%22).
+We have documented the current state of those PRs, and anyone is welcome to pick them up and
+continue the work on them.
+
+We have not imported all issues opened on the previous repository. For that reason, anyone wanting
+to **work on or discuss** an issue will have to follow the following workflow:
+
+- Recreate the issue
+- Start by referencing the **original issue**: ```Referencing issue #[<issue number>](<original
+  issue link>)```
+- Then, paste the original issues **opening** text
+
+You can then resume the conversation by replying to this new issue you have created.
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,44 +1,244 @@
 [package]
-name = "tui"
-version = "0.3.0-beta.0"
-authors = ["Florian Dehau <work@fdehau.com>"]
-description = """
-A library to build rich terminal user interfaces or dashboards
-"""
+name = "ratatui"
+version = "0.24.0" # crate version
+authors = ["Florian Dehau <work@fdehau.com>", "The Ratatui Developers"]
+description = "A library that's all about cooking up terminal user interfaces"
+documentation = "https://docs.rs/ratatui/latest/ratatui/"
 keywords = ["tui", "terminal", "dashboard"]
-repository = "https://github.com/fdehau/tui-rs"
+repository = "https://github.com/ratatui-org/ratatui"
+readme = "README.md"
 license = "MIT"
-exclude = ["docs/*", ".travis.yml"]
+exclude = [
+  "assets/*",
+  ".github",
+  "Makefile.toml",
+  "CONTRIBUTING.md",
+  "*.log",
+  "tags",
+]
 autoexamples = true
+edition = "2021"
+rust-version = "1.70.0"

 [badges]
-travis-ci = { repository = "fdehau/tui-rs" }
-
-[features]
-default = ["termion"]

 [dependencies]
-bitflags = "1.0"
+crossterm = { version = "0.27", optional = true }
+termion = { version = "2.0", optional = true }
+termwiz = { version = "0.20.0", optional = true }
+
+serde = { version = "1", optional = true, features = ["derive"] }
+bitflags = "2.3"
 cassowary = "0.3"
-itertools = "0.7"
-log = "0.4"
-either = "1.5"
-unicode-segmentation = "1.2"
+indoc = "2.0"
+itertools = "0.11"
+paste = "1.0.2"
+strum = { version = "0.25", features = ["derive"] }
+time = { version = "0.3.11", optional = true, features = ["local-offset"] }
+unicode-segmentation = "1.10"
 unicode-width = "0.1"
-termion = { version = "1.5", optional = true }
-rustbox = { version = "0.11", optional = true }
-crossterm = { version = "0.4", optional = true }
+document-features = { version = "0.2.7", optional = true }
+lru = "0.12.0"

 [dev-dependencies]
-stderrlog = "0.4"
-rand = "0.4"
+anyhow = "1.0.71"
+argh = "0.1.12"
+better-panic = "0.3.0"
+cargo-husky = { version = "1.5.0", default-features = false, features = [
+  "user-hooks",
+] }
+criterion = { version = "0.5.1", features = ["html_reports"] }
+fakeit = "1.1"
+rand = "0.8.5"
+palette = "0.7.3"
+pretty_assertions = "1.4.0"
+
+[features]
+#! The crate provides a set of optional features that can be enabled in your `cargo.toml` file.
+#!
+## By default, we enable the crossterm backend as this is a reasonable choice for most applications
+## as it is supported on Linux/Mac/Windows systems. We also enable the `underline-color` feature
+## which allows you to set the underline color of text.
+default = ["crossterm", "underline-color"]
+#! Generally an application will only use one backend, so you should only enable one of the following features:
+## enables the [`CrosstermBackend`] backend and adds a dependency on the [Crossterm crate].
+crossterm = ["dep:crossterm"]
+## enables the [`TermionBackend`] backend and adds a dependency on the [Termion crate].
+termion = ["dep:termion"]
+## enables the [`TermwizBackend`] backend and adds a dependency on the [Termwiz crate].
+termwiz = ["dep:termwiz"]
+
+#! The following optional features are available for all backends:
+## enables serialization and deserialization of style and color types using the [Serde crate].
+## This is useful if you want to save themes to a file.
+serde = ["dep:serde", "bitflags/serde"]
+
+## enables the [`border!`] macro.
+macros = []
+
+## enables all widgets.
+all-widgets = ["widget-calendar"]
+
+#! Widgets that add dependencies are gated behind feature flags to prevent unused transitive
+#! dependencies. The available features are:
+## enables the [`calendar`] widget module and adds a dependency on the [Time crate].
+widget-calendar = ["dep:time"]
+
+#! Underline color is only supported by the [`CrosstermBackend`] backend, and is not supported
+#! on Windows 7.
+## enables the backend code that sets the underline color.
+underline-color = ["dep:crossterm"]
+
+[package.metadata.docs.rs]
+all-features = true
+# see https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
+rustdoc-args = ["--cfg", "docsrs"]
+
+[[bench]]
+name = "barchart"
+harness = false
+
+[[bench]]
+name = "block"
+harness = false
+
+[[bench]]
+name = "list"
+harness = false
+
+[[bench]]
+name = "paragraph"
+harness = false
+
+[[bench]]
+name = "sparkline"
+harness = false
+

 [[example]]
-name = "rustbox"
-path = "examples/rustbox.rs"
-required-features = ["rustbox"]
-
-[[example]]
-name = "crossterm"
-path = "examples/crossterm.rs"
+name = "barchart"
 required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "block"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "canvas"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "calendar"
+required-features = ["crossterm", "widget-calendar"]
+doc-scrape-examples = true
+
+[[example]]
+name = "chart"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "colors"
+required-features = ["crossterm"]
+# this example is a bit verbose, so we don't want to include it in the docs
+doc-scrape-examples = false
+
+[[example]]
+name = "colors_rgb"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "custom_widget"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "demo"
+# this runs for all of the terminal backends, so it can't be built using --all-features or scraped
+doc-scrape-examples = false
+
+[[example]]
+name = "demo2"
+required-features = ["crossterm", "widget-calendar"]
+doc-scrape-examples = true
+
+[[example]]
+name = "docsrs"
+required-features = ["crossterm"]
+doc-scrape-examples = false
+
+[[example]]
+name = "gauge"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "hello_world"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "layout"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "list"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "modifiers"
+required-features = ["crossterm"]
+# this example is a bit verbose, so we don't want to include it in the docs
+doc-scrape-examples = false
+
+[[example]]
+name = "panic"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "paragraph"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "popup"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "scrollbar"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "sparkline"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "table"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "tabs"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "user_input"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "inline"
+required-features = ["crossterm"]
+doc-scrape-examples = true
--- a/3
+++ b/3
@@ -1,6 +1,7 @@
 The MIT License (MIT)

-Copyright (c) 2016 Florian Dehau
+Copyright (c) 2016-2022 Florian Dehau
+Copyright (c) 2023 The Ratatui Developers

 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
--- a/91
+++ b/91
@@ -1,91 +0,0 @@
-# Makefile for the tui-rs project (https://github.com/fdehau/tui-rs)
-
-
-# ================================ Cargo ======================================
-
-
-RUST_CHANNEL ?= stable
-CARGO_FLAGS =
-RUSTUP_INSTALLED = $(shell command -v rustup 2> /dev/null)
-
-ifndef RUSTUP_INSTALLED
-  CARGO = cargo
-else
-  ifdef CI
-    CARGO = cargo
-  else
-    CARGO = rustup run $(RUST_CHANNEL) cargo
-  endif
-endif
-
-
-# ================================ Help =======================================
-
-
-help: ## Print all the available commands
-	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
-	  awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
-
-
-# =============================== Build =======================================
-
-check: ## Validate the project code
-	$(CARGO) check
-
-build: ## Build the project in debug mode
-	$(CARGO) build $(CARGO_FLAGS)
-
-release: CARGO_FLAGS += --release
-release: build ## Build the project in release mode
-
-
-# ================================ Lint =======================================
-
-RUSTFMT_WRITEMODE ?= 'diff'
-
-lint: fmt clippy ## Lint project files
-
-fmt: ## Check the format of the source code
-	cargo fmt --all -- --check
-
-clippy: RUST_CHANNEL = nightly
-clippy: ## Check the style of the source code and catch common errors
-	$(CARGO) clippy --features="termion rustbox"
-
-
-# ================================ Test =======================================
-
-
-test: ## Run the tests
-	$(CARGO) test
-
-# ================================ Doc ========================================
-
-
-doc: ## Build the documentation (available at ./target/doc)
-	$(CARGO) doc
-
-
-# ================================= Watch =====================================
-
-# Requires watchman and watchman-make (https://facebook.github.io/watchman/docs/install.html)
-
-watch: ## Watch file changes and build the project if any
-	watchman-make -p 'src/**/*.rs' -t check build
-
-watch-test: ## Watch files changes and run the tests if any
-	watchman-make -p 'src/**/*.rs' 'tests/**/*.rs' 'examples/**/*.rs' -t test
-
-watch-doc: ## Watch file changes and rebuild the documentation if any
-	watchman-make -p 'src/**/*.rs' -t doc
-
-# ================================= Pipelines =================================
-
-stable: RUST_CHANNEL = stable
-stable: build test ## Run build and tests for stable
-
-beta: RUST_CHANNEL = beta
-beta: build test ## Run build and tests for beta
-
-nightly: RUST_CHANNEL = nightly
-nightly: build lint test ## Run build, lint and tests for nightly
--- a/Makefile.toml
+++ b/Makefile.toml
@@ -0,0 +1,163 @@
+# configuration for https://github.com/sagiegurari/cargo-make
+
+[config]
+skip_core_tasks = true
+
+[env]
+# all features except the backend ones
+ALL_FEATURES = "all-widgets,macros,serde"
+
+# Windows does not support building termion, so this avoids the build failure by providing two
+# sets of flags, one for Windows and one for other platforms.
+# Windows: --features=all-widgets,macros,serde,crossterm,termwiz,underline-color
+# Other: --features=all-widgets,macros,serde,crossterm,termion,termwiz,underline-color
+ALL_FEATURES_FLAG = { source = "${CARGO_MAKE_RUST_TARGET_OS}", default_value = "--features=all-widgets,macros,serde,crossterm,termion,termwiz", mapping = { "windows" = "--features=all-widgets,macros,serde,crossterm,termwiz" } }
+
+[tasks.default]
+alias = "ci"
+
+[tasks.ci]
+description = "Run continuous integration tasks"
+dependencies = ["lint-style", "clippy", "check", "test"]
+
+[tasks.lint-style]
+description = "Lint code style (formatting, typos, docs)"
+dependencies = ["lint-format", "lint-typos", "lint-docs"]
+
+[tasks.lint-format]
+description = "Lint code formatting"
+toolchain = "nightly"
+command = "cargo"
+args = ["fmt", "--all", "--check"]
+
+[tasks.format]
+description = "Fix code formatting"
+toolchain = "nightly"
+command = "cargo"
+args = ["fmt", "--all"]
+
+[tasks.lint-typos]
+description = "Run typo checks"
+install_crate = { crate_name = "typos-cli", binary = "typos", test_arg = "--version" }
+command = "typos"
+
+[tasks.lint-docs]
+description = "Check documentation for errors and warnings"
+toolchain = "nightly"
+command = "cargo"
+args = [
+  "rustdoc",
+  "--no-default-features",
+  "${ALL_FEATURES_FLAG}",
+  "--",
+  "-Zunstable-options",
+  "--check",
+  "-Dwarnings",
+]
+
+[tasks.check]
+description = "Check code for errors and warnings"
+command = "cargo"
+args = [
+  "check",
+  "--all-targets",
+  "--no-default-features",
+  "${ALL_FEATURES_FLAG}",
+]
+
+[tasks.build]
+description = "Compile the project"
+command = "cargo"
+args = [
+  "build",
+  "--all-targets",
+  "--no-default-features",
+  "${ALL_FEATURES_FLAG}",
+]
+
+[tasks.clippy]
+description = "Run Clippy for linting"
+command = "cargo"
+args = [
+  "clippy",
+  "--all-targets",
+  "--tests",
+  "--benches",
+  "--no-default-features",
+  "${ALL_FEATURES_FLAG}",
+  "--",
+  "-D",
+  "warnings",
+]
+
+[tasks.test]
+description = "Run tests"
+dependencies = ["test-doc"]
+command = "cargo"
+args = [
+  "test",
+  "--all-targets",
+  "--no-default-features",
+  "${ALL_FEATURES_FLAG}",
+]
+
+[tasks.test-doc]
+description = "Run documentation tests"
+command = "cargo"
+args = ["test", "--doc", "--no-default-features", "${ALL_FEATURES_FLAG}"]
+
+[tasks.test-backend]
+# takes a command line parameter to specify the backend to test (e.g. "crossterm")
+description = "Run backend-specific tests"
+command = "cargo"
+args = [
+  "test",
+  "--all-targets",
+  "--no-default-features",
+  "--features",
+  "${ALL_FEATURES},${@}",
+]
+
+[tasks.coverage]
+description = "Generate code coverage report"
+command = "cargo"
+args = [
+  "llvm-cov",
+  "--lcov",
+  "--output-path",
+  "target/lcov.info",
+  "--no-default-features",
+  "${ALL_FEATURES_FLAG}",
+]
+
+[tasks.run-example]
+private = true
+condition = { env_set = ["TUI_EXAMPLE_NAME"] }
+command = "cargo"
+args = [
+  "run",
+  "--release",
+  "--example",
+  "${TUI_EXAMPLE_NAME}",
+  "--features",
+  "all-widgets",
+]
+
+[tasks.build-examples]
+description = "Compile project examples"
+command = "cargo"
+args = ["build", "--examples", "--release", "--features", "all-widgets"]
+
+[tasks.run-examples]
+description = "Run project examples"
+dependencies = ["build-examples"]
+script = '''
+#!@duckscript
+files = glob_array ./examples/*.rs
+for file in ${files}
+  name = basename ${file}
+  name = substring ${name} -3
+  set_env TUI_EXAMPLE_NAME ${name}
+  cm_run_task run-example
+end
+'''
--- a/README.md
+++ b/README.md
@@ -1,68 +1,443 @@
-# tui-rs
+<details>
+<summary>Table of Contents</summary>

-[![Build Status](https://travis-ci.org/fdehau/tui-rs.svg?branch=master)](https://travis-ci.org/fdehau/tui-rs)
-[![Crate Status](https://img.shields.io/crates/v/tui.svg)](https://crates.io/crates/tui)
-[![Docs Status](https://docs.rs/tui/badge.svg)](https://docs.rs/crate/tui/)
+- [Ratatui](#ratatui)
+  - [Installation](#installation)
+  - [Introduction](#introduction)
+  - [Other Documentation](#other-documentation)
+  - [Quickstart](#quickstart)
+  - [Status of this fork](#status-of-this-fork)
+  - [Rust version requirements](#rust-version-requirements)
+  - [Widgets](#widgets)
+    - [Built in](#built-in)
+    - [Third\-party libraries, bootstrapping templates and
+      widgets](#third-party-libraries-bootstrapping-templates-and-widgets)
+  - [Apps](#apps)
+  - [Alternatives](#alternatives)
+  - [Acknowledgments](#acknowledgments)
+  - [License](#license)

-<img src="./docs/demo.gif" alt="Demo cast under Linux Termite with Inconsolata font 12pt">
+</details>

-`tui-rs` is a [Rust](https://www.rust-lang.org) library to build rich terminal
-user interfaces and dashboards. It is heavily inspired by the `Javascript`
-library [blessed-contrib](https://github.com/yaronn/blessed-contrib) and the
-`Go` library [termui](https://github.com/gizak/termui).
+<!-- cargo-rdme start -->

-The library itself supports two different backends to draw to the terminal. You
-can either choose from:
+![Demo](https://raw.githubusercontent.com/ratatui-org/ratatui/b33c878808c4c40591d7a2d9f9d94d6fee95a96f/examples/demo2.gif)

-  - [termion](https://github.com/ticki/termion)
-  - [rustbox](https://github.com/gchp/rustbox)
+<div align="center">

-However, some features may only be available in one of the two.
+[![Crate Badge]](https://crates.io/crates/ratatui) [![License Badge]](./LICENSE) [![CI
+Badge]](https://github.com/ratatui-org/ratatui/actions?query=workflow%3ACI+) [![Docs
+Badge]](https://docs.rs/crate/ratatui/)<br>
+[![Dependencies Badge]](https://deps.rs/repo/github/ratatui-org/ratatui) [![Codecov
+Badge]](https://app.codecov.io/gh/ratatui-org/ratatui) [![Discord
+Badge]](https://discord.gg/pMCEU9hNEj) [![Matrix
+Badge]](https://matrix.to/#/#ratatui:matrix.org)<br>
+[Documentation](https://docs.rs/ratatui) · [Ratatui Book](https://ratatui.rs) ·
+[Examples](https://github.com/ratatui-org/ratatui/tree/main/examples) · [Report a
+bug](https://github.com/ratatui-org/ratatui/issues/new?labels=bug&projects=&template=bug_report.md)
+· [Request a
+Feature](https://github.com/ratatui-org/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md)
+· [Send a Pull Request](https://github.com/ratatui-org/ratatui/compare)

-The library is based on the principle of immediate rendering with intermediate
-buffers. This means that at each new frame you should build all widgets that are
-supposed to be part of the UI. While providing a great flexibility for rich and
-interactive UI, this may introduce overhead for highly dynamic content. So, the
-implementation try to minimize the number of ansi escapes sequences generated to
-draw the updated UI. In practice, given the speed of `Rust` the overhead rather
-comes from the terminal emulator than the library itself.
+</div>

-Moreover, the library does not provide any input handling nor any event system and
-you may rely on the previously cited libraries to achieve such features.
+# Ratatui

-### [Documentation](https://docs.rs/tui)
+[Ratatui] is a crate for cooking up terminal user interfaces in rust. It is a lightweight
+library that provides a set of widgets and utilities to build complex rust TUIs. Ratatui was
+forked from the [Tui-rs crate] in 2023 in order to continue its development.

-### Demo
+## Installation

-The [source code](examples/demo.rs) of the demo gif.
+Add `ratatui` and `crossterm` as dependencies to your cargo.toml:

-### Widgets
+```shell
+cargo add ratatui crossterm
+```

-The library comes with the following list of widgets:
+Ratatui uses [Crossterm] by default as it works on most platforms. See the [Installation]
+section of the [Ratatui Book] for more details on how to use other backends ([Termion] /
+[Termwiz]).

-  * [Block](examples/block.rs)
-  * [Gauge](examples/gauge.rs)
-  * [Sparkline](examples/sparkline.rs)
-  * [Chart](examples/chart.rs)
-  * [BarChart](examples/bar_chart.rs)
-  * [List](examples/list.rs)
-  * [Table](examples/table.rs)
-  * [Paragraph](examples/paragraph.rs)
-  * [Canvas (with line, point cloud, map)](examples/canvas.rs)
-  * [Tabs](examples/tabs.rs)
+## Introduction

-Click on each item to see the source of the example. Run the examples with with 
-cargo (e.g. to run the demo `cargo run --example demo`), and quit by pressing `q`.
+Ratatui is based on the principle of immediate rendering with intermediate buffers. This means
+that for each frame, your app must render all widgets that are supposed to be part of the UI.
+This is in contrast to the retained mode style of rendering where widgets are updated and then
+automatically redrawn on the next frame. See the [Rendering] section of the [Ratatui Book] for
+more info.

-### Third-party widgets
+## Other documentation

-* [tui-logger](https://github.com/gin66/tui-logger)
+- [Ratatui Book] - explains the library's concepts and provides step-by-step tutorials
+- [Examples] - a collection of examples that demonstrate how to use the library.
+- [API Documentation] - the full API documentation for the library on docs.rs.
+- [Changelog] - generated by [git-cliff] utilizing [Conventional Commits].
+- [Contributing] - Please read this if you are interested in contributing to the project.
+- [Breaking Changes] - a list of breaking changes in the library.

-### Alternatives
+## Quickstart

-You might want to checkout [Cursive](https://github.com/gyscos/Cursive) for an
-alternative solution to build text user interfaces in Rust.
+The following example demonstrates the minimal amount of code necessary to setup a terminal and
+render "Hello World!". The full code for this example which contains a little more detail is in
+[hello_world.rs]. For more guidance on different ways to structure your application see the
+[Application Patterns] and [Hello World tutorial] sections in the [Ratatui Book] and the various
+[Examples]. There are also several starter templates available:
+
+- [rust-tui-template]
+- [ratatui-async-template] (book and template)
+- [simple-tui-rs]
+
+Every application built with `ratatui` needs to implement the following steps:
+
+- Initialize the terminal
+- A main loop to:
+  - Handle input events
+  - Draw the UI
+- Restore the terminal state
+
+The library contains a [`prelude`] module that re-exports the most commonly used traits and
+types for convenience. Most examples in the documentation will use this instead of showing the
+full path of each type.
+
+### Initialize and restore the terminal
+
+The [`Terminal`] type is the main entry point for any Ratatui application. It is a light
+abstraction over a choice of [`Backend`] implementations that provides functionality to draw
+each frame, clear the screen, hide the cursor, etc. It is parametrized over any type that
+implements the [`Backend`] trait which has implementations for [Crossterm], [Termion] and
+[Termwiz].
+
+Most applications should enter the Alternate Screen when starting and leave it when exiting and
+also enable raw mode to disable line buffering and enable reading key events. See the [`backend`
+module] and the [Backends] section of the [Ratatui Book] for more info.
+
+### Drawing the UI
+
+The drawing logic is delegated to a closure that takes a [`Frame`] instance as argument. The
+[`Frame`] provides the size of the area to draw to and allows the app to render any [`Widget`]
+using the provided [`render_widget`] method. See the [Widgets] section of the [Ratatui Book] for
+more info.
+
+### Handling events
+
+Ratatui does not include any input handling. Instead event handling can be implemented by
+calling backend library methods directly. See the [Handling Events] section of the [Ratatui
+Book] for more info. For example, if you are using [Crossterm], you can use the
+[`crossterm::event`] module to handle events.
+
+### Example
+
+```rust
+use std::io::{self, stdout};
+use crossterm::{
+    event::{self, Event, KeyCode},
+    ExecutableCommand,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen}
+};
+use ratatui::{prelude::*, widgets::*};
+
+fn main() -> io::Result<()> {
+    enable_raw_mode()?;
+    stdout().execute(EnterAlternateScreen)?;
+    let mut terminal = Terminal::new(CrosstermBackend::new(stdout()))?;
+
+    let mut should_quit = false;
+    while !should_quit {
+        terminal.draw(ui)?;
+        should_quit = handle_events()?;
+    }
+
+    disable_raw_mode()?;
+    stdout().execute(LeaveAlternateScreen)?;
+    Ok(())
+}
+
+fn handle_events() -> io::Result<bool> {
+    if event::poll(std::time::Duration::from_millis(50))? {
+        if let Event::Key(key) = event::read()? {
+            if key.kind == event::KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                return Ok(true);
+            }
+       }
+    }
+    Ok(false)
+}
+
+fn ui(frame: &mut Frame) {
+    frame.render_widget(
+        Paragraph::new("Hello World!")
+            .block(Block::default().title("Greeting").borders(Borders::ALL)),
+        frame.size(),
+    );
+}
+```
+
+Running this example produces the following output:
+
+![docsrs-hello]
+
+## Layout
+
+The library comes with a basic yet useful layout management object called [`Layout`] which
+allows you to split the available space into multiple areas and then render widgets in each
+area. This lets you describe a responsive terminal UI by nesting layouts. See the [Layout]
+section of the [Ratatui Book] for more info.
+
+```rust
+use ratatui::{prelude::*, widgets::*};
+
+fn ui(frame: &mut Frame) {
+    let main_layout = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(1),
+            Constraint::Min(0),
+            Constraint::Length(1),
+        ])
+        .split(frame.size());
+    frame.render_widget(
+        Block::new().borders(Borders::TOP).title("Title Bar"),
+        main_layout[0],
+    );
+    frame.render_widget(
+        Block::new().borders(Borders::TOP).title("Status Bar"),
+        main_layout[2],
+    );
+
+    let inner_layout = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
+        .split(main_layout[1]);
+    frame.render_widget(
+        Block::default().borders(Borders::ALL).title("Left"),
+        inner_layout[0],
+    );
+    frame.render_widget(
+        Block::default().borders(Borders::ALL).title("Right"),
+        inner_layout[1],
+    );
+}
+```
+
+Running this example produces the following output:
+
+![docsrs-layout]
+
+## Text and styling
+
+The [`Text`], [`Line`] and [`Span`] types are the building blocks of the library and are used in
+many places. [`Text`] is a list of [`Line`]s and a [`Line`] is a list of [`Span`]s. A [`Span`]
+is a string with a specific style.
+
+The [`style` module] provides types that represent the various styling options. The most
+important one is [`Style`] which represents the foreground and background colors and the text
+attributes of a [`Span`]. The [`style` module] also provides a [`Stylize`] trait that allows
+short-hand syntax to apply a style to widgets and text. See the [Styling Text] section of the
+[Ratatui Book] for more info.
+
+```rust
+use ratatui::{prelude::*, widgets::*};
+
+fn ui(frame: &mut Frame) {
+    let areas = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(1),
+            Constraint::Length(1),
+            Constraint::Length(1),
+            Constraint::Length(1),
+            Constraint::Min(0),
+        ])
+        .split(frame.size());
+
+    let span1 = Span::raw("Hello ");
+    let span2 = Span::styled(
+        "World",
+        Style::new()
+            .fg(Color::Green)
+            .bg(Color::White)
+            .add_modifier(Modifier::BOLD),
+    );
+    let span3 = "!".red().on_light_yellow().italic();
+
+    let line = Line::from(vec![span1, span2, span3]);
+    let text: Text = Text::from(vec![line]);
+
+    frame.render_widget(Paragraph::new(text), areas[0]);
+    // or using the short-hand syntax and implicit conversions
+    frame.render_widget(
+        Paragraph::new("Hello World!".red().on_white().bold()),
+        areas[1],
+    );
+
+    // to style the whole widget instead of just the text
+    frame.render_widget(
+        Paragraph::new("Hello World!").style(Style::new().red().on_white()),
+        areas[2],
+    );
+    // or using the short-hand syntax
+    frame.render_widget(Paragraph::new("Hello World!").blue().on_yellow(), areas[3]);
+}
+```
+
+Running this example produces the following output:
+
+![docsrs-styling]
+
+[Ratatui Book]: https://ratatui.rs
+[Installation]: https://ratatui.rs/installation.html
+[Rendering]: https://ratatui.rs/concepts/rendering/index.html
+[Application Patterns]: https://ratatui.rs/concepts/application_patterns/index.html
+[Hello World tutorial]: https://ratatui.rs/tutorial/hello_world.html
+[Backends]: https://ratatui.rs/concepts/backends/index.html
+[Widgets]: https://ratatui.rs/how-to/widgets/index.html
+[Handling Events]: https://ratatui.rs/concepts/event_handling.html
+[Layout]: https://ratatui.rs/how-to/layout/index.html
+[Styling Text]: https://ratatui.rs/how-to/render/style-text.html
+[rust-tui-template]: https://github.com/ratatui-org/rust-tui-template
+[ratatui-async-template]: https://ratatui-org.github.io/ratatui-async-template/
+[simple-tui-rs]: https://github.com/pmsanford/simple-tui-rs
+[Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples
+[git-cliff]: https://github.com/orhun/git-cliff
+[Conventional Commits]: https://www.conventionalcommits.org
+[API Documentation]: https://docs.rs/ratatui
+[Changelog]: https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.md
+[Contributing]: https://github.com/ratatui-org/ratatui/blob/main/CONTRIBUTING.md
+[Breaking Changes]: https://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md
+[docsrs-hello]: https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-hello.png?raw=true
+[docsrs-layout]: https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-layout.png?raw=true
+[docsrs-styling]: https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-styling.png?raw=true
+[`Frame`]: terminal::Frame
+[`render_widget`]: terminal::Frame::render_widget
+[`Widget`]: widgets::Widget
+[`Layout`]: layout::Layout
+[`Text`]: text::Text
+[`Line`]: text::Line
+[`Span`]: text::Span
+[`Style`]: style::Style
+[`style` module]: style
+[`Stylize`]: style::Stylize
+[`Backend`]: backend::Backend
+[`backend` module]: backend
+[`crossterm::event`]: https://docs.rs/crossterm/latest/crossterm/event/index.html
+[Ratatui]: https://ratatui.rs
+[Crossterm]: https://crates.io/crates/crossterm
+[Termion]: https://crates.io/crates/termion
+[Termwiz]: https://crates.io/crates/termwiz
+[Tui-rs crate]: https://crates.io/crates/tui
+[hello_world.rs]: https://github.com/ratatui-org/ratatui/blob/main/examples/hello_world.rs
+[Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square
+[CI Badge]:
+    https://img.shields.io/github/actions/workflow/status/ratatui-org/ratatui/ci.yml?style=flat-square&logo=github
+[Codecov Badge]:
+    https://img.shields.io/codecov/c/github/ratatui-org/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST
+[Dependencies Badge]: https://deps.rs/repo/github/ratatui-org/ratatui/status.svg?style=flat-square
+[Discord Badge]:
+    https://img.shields.io/discord/1070692720437383208?label=discord&logo=discord&style=flat-square
+[Docs Badge]: https://img.shields.io/docsrs/ratatui?logo=rust&style=flat-square
+[License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square
+[Matrix Badge]:
+    https://img.shields.io/matrix/ratatui-general%3Amatrix.org?style=flat-square&logo=matrix&label=Matrix
+
+<!-- cargo-rdme end -->
+
+## Status of this fork
+
+In response to the original maintainer [**Florian Dehau**](https://github.com/fdehau)'s issue
+regarding the [future of `tui-rs`](https://github.com/fdehau/tui-rs/issues/654), several members of
+the community forked the project and created this crate. We look forward to continuing the work
+started by Florian 🚀
+
+In order to organize ourselves, we currently use a [Discord server](https://discord.gg/pMCEU9hNEj),
+feel free to join and come chat! There is also a [Matrix](https://matrix.org/) bridge available at
+[#ratatui:matrix.org](https://matrix.to/#/#ratatui:matrix.org).
+
+While we do utilize Discord for coordinating, it's not essential for contributing.
+Our primary open-source workflow is centered around GitHub.
+For significant discussions, we rely on GitHub — please open an issue, a discussion or a PR.
+
+Please make sure you read the updated [contributing](./CONTRIBUTING.md) guidelines, especially if
+you are interested in working on a PR or issue opened in the previous repository.
+
+## Rust version requirements
+
+Since version 0.23.0, The Minimum Supported Rust Version (MSRV) of `ratatui` is 1.67.0.
+
+## Widgets
+
+### Built in
+
+The library comes with the following
+[widgets](https://docs.rs/ratatui/latest/ratatui/widgets/index.html):
+
+- [BarChart](https://docs.rs/ratatui/latest/ratatui/widgets/struct.BarChart.html)
+- [Block](https://docs.rs/ratatui/latest/ratatui/widgets/block/struct.Block.html)
+- [Calendar](https://docs.rs/ratatui/latest/ratatui/widgets/calendar/index.html)
+- [Canvas](https://docs.rs/ratatui/latest/ratatui/widgets/canvas/struct.Canvas.html) which allows
+  rendering [points, lines, shapes and a world
+  map](https://docs.rs/ratatui/latest/ratatui/widgets/canvas/index.html)
+- [Chart](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Chart.html)
+- [Clear](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Clear.html)
+- [Gauge](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Gauge.html)
+- [List](https://docs.rs/ratatui/latest/ratatui/widgets/struct.List.html)
+- [Paragraph](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Paragraph.html)
+- [Scrollbar](https://docs.rs/ratatui/latest/ratatui/widgets/scrollbar/struct.Scrollbar.html)
+- [Sparkline](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Sparkline.html)
+- [Table](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Table.html)
+- [Tabs](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Tabs.html)
+
+Each widget has an associated example which can be found in the [examples](./examples/) folder. Run
+each examples with cargo (e.g. to run the gauge example `cargo run --example gauge`), and quit by
+pressing `q`.
+
+You can also run all examples by running `cargo make run-examples` (requires `cargo-make` that can
+be installed with `cargo install cargo-make`).
+
+### Third-party libraries, bootstrapping templates and widgets
+
+- [ansi-to-tui](https://github.com/uttarayan21/ansi-to-tui) — Convert ansi colored text to
+  `ratatui::text::Text`
+- [color-to-tui](https://github.com/uttarayan21/color-to-tui) — Parse hex colors to
+  `ratatui::style::Color`
+- [rust-tui-template](https://github.com/ratatui-org/rust-tui-template) — A template for
+  bootstrapping a Rust TUI application with Tui-rs & crossterm
+- [simple-tui-rs](https://github.com/pmsanford/simple-tui-rs) — A simple example tui-rs app
+- [tui-builder](https://github.com/jkelleyrtp/tui-builder) — Batteries-included MVC framework for
+  Tui-rs + Crossterm apps
+- [tui-clap](https://github.com/kegesch/tui-clap-rs) — Use clap-rs together with Tui-rs
+- [tui-log](https://github.com/kegesch/tui-log-rs) — Example of how to use logging with Tui-rs
+- [tui-logger](https://github.com/gin66/tui-logger) — Logger and Widget for Tui-rs
+- [tui-realm](https://github.com/veeso/tui-realm) — Tui-rs framework to build stateful applications
+  with a React/Elm inspired approach
+- [tui-realm-treeview](https://github.com/veeso/tui-realm-treeview) — Treeview component for
+  Tui-realm
+- [tui-rs-tree-widgets](https://github.com/EdJoPaTo/tui-rs-tree-widget) — Widget for tree data
+  structures.
+- [tui-windows](https://github.com/markatk/tui-windows-rs) — Tui-rs abstraction to handle multiple
+  windows and their rendering
+- [tui-textarea](https://github.com/rhysd/tui-textarea) — Simple yet powerful multi-line text editor
+  widget supporting several key shortcuts, undo/redo, text search, etc.
+- [tui-input](https://github.com/sayanarijit/tui-input) — TUI input library supporting multiple
+  backends and tui-rs.
+- [tui-term](https://github.com/a-kenji/tui-term) — A pseudoterminal widget library
+  that enables the rendering of terminal applications as ratatui widgets.
+
+## Apps
+
+Check out the list of more than 50 [Apps using
+`Ratatui`](https://github.com/ratatui-org/ratatui/wiki/Apps-using-Ratatui)!
+
+## Alternatives
+
+You might want to checkout [Cursive](https://github.com/gyscos/Cursive) for an alternative solution
+to build text user interfaces in Rust.
+
+## Acknowledgments
+
+Special thanks to [**Pavel Fomchenkov**](https://github.com/nawok) for his work in designing **an
+awesome logo** for the ratatui project and ratatui-org organization.

 ## License

-[MIT](LICENSE)
+[MIT](./LICENSE)
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -0,0 +1,44 @@
+# Creating a Release
+
+[crates.io](https://crates.io/crates/ratatui) releases are automated via [GitHub
+actions](.github/workflows/cd.yml) and triggered by pushing a tag.
+
+1. Record a new demo gif if necessary. The preferred tool for this is
+[vhs](https://github.com/charmbracelet/vhs) (installation instructions in README).
+
+   ```shell
+   cargo build --example demo2
+   vhs examples/demo2.tape
+   ```
+
+1. Switch branches to the images branch and copy demo2.gif to examples/, commit, and push.
+1. Grab the permalink from <https://github.com/ratatui-org/ratatui/blob/images/examples/demo2.gif> and
+   append `?raw=true` to redirect to the actual image url. Then update the link in the main README.
+   Avoid adding the gif to the git repo as binary files tend to bloat repositories.
+
+1. Bump the version in [Cargo.toml](Cargo.toml).
+1. Ensure [CHANGELOG.md](CHANGELOG.md) is updated. [git-cliff](https://github.com/orhun/git-cliff)
+   can be used for generating the entries.
+1. Ensure that any breaking changes are documented in [BREAKING-CHANGES.md](./BREAKING-CHANGES.md)
+1. Commit and push the changes.
+1. Create a new tag: `git tag -a v[X.Y.Z]`
+1. Push the tag: `git push --tags`
+1. Wait for [Continuous Deployment](https://github.com/ratatui-org/ratatui/actions) workflow to
+   finish.
+
+## Alpha Releases
+
+Alpha releases are automatically released every Saturday via [cd.yml](./.github/workflows/cd.yml)
+and can be manually be created when necessary by triggering the [Continuous
+Deployment](https://github.com/ratatui-org/ratatui/actions/workflows/cd.yml) workflow.
+
+We automatically release an alpha release with a patch level bump + alpha.num weekly (and when we
+need to manually). E.g. the last release was 0.22.0, and the most recent alpha release is
+0.22.1-alpha.1.
+
+These releases will have whatever happened to be in main at the time of release, so they're useful
+for apps that need to get releases from crates.io, but may contain more bugs and be generally less
+tested than normal releases.
+
+See [#147](https://github.com/ratatui-org/ratatui/issues/147) and
+[#359](https://github.com/ratatui-org/ratatui/pull/359) for more info on the alpha release process.
--- a/assets/favicon.ico
+++ b/assets/favicon.ico
--- a/assets/logo.png
+++ b/assets/logo.png
--- a/bacon.toml
+++ b/bacon.toml
@@ -0,0 +1,100 @@
+# This is a configuration file for the bacon tool
+#
+# Bacon repository: https://github.com/Canop/bacon
+# Complete help on configuration: https://dystroy.org/bacon/config/
+# You can also check bacon's own bacon.toml file
+#  as an example: https://github.com/Canop/bacon/blob/main/bacon.toml
+
+default_job = "check"
+
+[jobs.check]
+command = ["cargo", "check", "--all-features", "--color", "always"]
+need_stdout = false
+
+[jobs.check-all]
+command = ["cargo", "check", "--all-targets", "--all-features", "--color", "always"]
+need_stdout = false
+
+[jobs.check-crossterm]
+command = ["cargo", "check", "--color", "always", "--all-targets", "--no-default-features", "--features", "crossterm"]
+need_stdout = false
+
+[jobs.check-termion]
+command = ["cargo", "check", "--color", "always", "--all-targets", "--no-default-features", "--features", "termion"]
+need_stdout = false
+
+[jobs.check-termwiz]
+command = ["cargo", "check", "--color", "always", "--all-targets", "--no-default-features", "--features", "termwiz"]
+need_stdout = false
+
+[jobs.clippy]
+command = [
+    "cargo", "clippy",
+    "--all-targets",
+    "--color", "always",
+]
+need_stdout = false
+
+[jobs.test]
+command = [
+    "cargo", "test",
+    "--all-features",
+    "--color", "always",
+    "--", "--color", "always", # see https://github.com/Canop/bacon/issues/124
+]
+need_stdout = true
+
+[jobs.doc]
+command = [
+    "cargo", "+nightly", "doc",
+    "-Zunstable-options", "-Zrustdoc-scrape-examples",
+    "--all-features",
+    "--color", "always",
+    "--no-deps",
+]
+env.RUSTDOCFLAGS = "--cfg docsrs"
+need_stdout = false
+
+# If the doc compiles, then it opens in your browser and bacon switches
+# to the previous job
+[jobs.doc-open]
+command = [
+    "cargo", "+nightly", "doc",
+    "-Zunstable-options", "-Zrustdoc-scrape-examples",
+    "--all-features",
+    "--color", "always",
+    "--no-deps",
+    "--open",
+]
+env.RUSTDOCFLAGS = "--cfg docsrs"
+need_stdout = false
+on_success = "job:doc" # so that we don't open the browser at each change
+
+[jobs.coverage]
+command = [
+    "cargo", "llvm-cov",
+    "--lcov", "--output-path", "target/lcov.info",
+    "--all-features", 
+    "--color", "always",
+]
+
+[jobs.coverage-unit-tests-only]
+command = [
+    "cargo", "llvm-cov",
+    "--lcov", "--output-path", "target/lcov.info",
+    "--lib",
+    "--all-features",
+    "--color", "always",
+]
+
+# You may define here keybindings that would be specific to
+# a project, for example a shortcut to launch a specific job.
+# Shortcuts to internal functions (scrolling, toggling, etc.)
+# should go in your personal global prefs.toml file instead.
+[keybindings]
+# alt-m = "job:my-job"
+ctrl-c = "job:check-crossterm"
+ctrl-t = "job:check-termion"
+ctrl-w = "job:check-termwiz"
+v = "job:coverage"
+u = "job:coverage-unit-tests-only"
--- a/benches/barchart.rs
+++ b/benches/barchart.rs
@@ -0,0 +1,73 @@
+use criterion::{criterion_group, criterion_main, Bencher, BenchmarkId, Criterion};
+use rand::Rng;
+use ratatui::{
+    buffer::Buffer,
+    layout::Rect,
+    prelude::Direction,
+    widgets::{Bar, BarChart, BarGroup, Widget},
+};
+
+/// Benchmark for rendering a barchart.
+pub fn barchart(c: &mut Criterion) {
+    let mut group = c.benchmark_group("barchart");
+    let mut rng = rand::thread_rng();
+
+    for data_count in [64, 256, 2048] {
+        let data: Vec<Bar> = (0..data_count)
+            .map(|i| {
+                Bar::default()
+                    .label(format!("B{i}").into())
+                    .value(rng.gen_range(0..data_count))
+            })
+            .collect();
+
+        let bargroup = BarGroup::default().bars(&data);
+
+        // Render a basic barchart
+        group.bench_with_input(
+            BenchmarkId::new("render", data_count),
+            &BarChart::default().data(bargroup.clone()),
+            render,
+        );
+
+        // Render an horizontal barchart
+        group.bench_with_input(
+            BenchmarkId::new("render_horizontal", data_count),
+            &BarChart::default()
+                .direction(Direction::Horizontal)
+                .data(bargroup.clone()),
+            render,
+        );
+
+        // Render a barchart with multiple groups
+        group.bench_with_input(
+            BenchmarkId::new("render_grouped", data_count),
+            &BarChart::default()
+                // We call `data` multiple time to add multiple groups.
+                // This is not a duplicated call.
+                .data(bargroup.clone())
+                .data(bargroup.clone())
+                .data(bargroup.clone()),
+            render,
+        );
+    }
+
+    group.finish();
+}
+
+/// Render the widget in a classical size buffer
+fn render(bencher: &mut Bencher, barchart: &BarChart) {
+    let mut buffer = Buffer::empty(Rect::new(0, 0, 200, 50));
+    // We use `iter_batched` to clone the value in the setup function.
+    // See https://github.com/ratatui-org/ratatui/pull/377.
+    bencher.iter_batched(
+        || barchart.clone(),
+        |bench_barchart| {
+            bench_barchart.render(buffer.area, &mut buffer);
+        },
+        criterion::BatchSize::LargeInput,
+    )
+}
+
+criterion_group!(benches, barchart);
+criterion_main!(benches);
--- a/benches/block.rs
+++ b/benches/block.rs
@@ -0,0 +1,64 @@
+use criterion::{criterion_group, criterion_main, BatchSize, Bencher, BenchmarkId, Criterion};
+use ratatui::{
+    buffer::Buffer,
+    layout::Rect,
+    prelude::Alignment,
+    widgets::{
+        block::{Position, Title},
+        Block, Borders, Padding, Widget,
+    },
+};
+
+/// Benchmark for rendering a block.
+pub fn block(c: &mut Criterion) {
+    let mut group = c.benchmark_group("block");
+
+    for buffer_size in &[
+        Rect::new(0, 0, 100, 50),  // vertically split screen
+        Rect::new(0, 0, 200, 50),  // 1080p fullscreen with medium font
+        Rect::new(0, 0, 256, 256), // Max sized area
+    ] {
+        let buffer_area = buffer_size.area();
+
+        // Render an empty block
+        group.bench_with_input(
+            BenchmarkId::new("render_empty", buffer_area),
+            &Block::new(),
+            |b, block| render(b, block, buffer_size),
+        );
+
+        // Render with all features
+        group.bench_with_input(
+            BenchmarkId::new("render_all_feature", buffer_area),
+            &Block::new()
+                .borders(Borders::ALL)
+                .title("test title")
+                .title(
+                    Title::from("bottom left title")
+                        .alignment(Alignment::Right)
+                        .position(Position::Bottom),
+                )
+                .padding(Padding::new(5, 5, 2, 2)),
+            |b, block| render(b, block, buffer_size),
+        );
+    }
+
+    group.finish();
+}
+
+/// render the block into a buffer of the given `size`
+fn render(bencher: &mut Bencher, block: &Block, size: &Rect) {
+    let mut buffer = Buffer::empty(*size);
+    // We use `iter_batched` to clone the value in the setup function.
+    // See https://github.com/ratatui-org/ratatui/pull/377.
+    bencher.iter_batched(
+        || block.to_owned(),
+        |bench_block| {
+            bench_block.render(buffer.area, &mut buffer);
+        },
+        BatchSize::SmallInput,
+    )
+}
+
+criterion_group!(benches, block);
+criterion_main!(benches);
--- a/benches/list.rs
+++ b/benches/list.rs
@@ -0,0 +1,73 @@
+use criterion::{criterion_group, criterion_main, BatchSize, Bencher, BenchmarkId, Criterion};
+use ratatui::{
+    buffer::Buffer,
+    layout::Rect,
+    widgets::{List, ListItem, ListState, StatefulWidget, Widget},
+};
+
+/// Benchmark for rendering a list.
+/// It only benchmarks the render with a different amount of items.
+pub fn list(c: &mut Criterion) {
+    let mut group = c.benchmark_group("list");
+
+    for line_count in [64, 2048, 16384] {
+        let lines: Vec<ListItem> = (0..line_count)
+            .map(|_| ListItem::new(fakeit::words::sentence(10)))
+            .collect();
+
+        // Render default list
+        group.bench_with_input(
+            BenchmarkId::new("render", line_count),
+            &List::new(lines.clone()),
+            render,
+        );
+
+        // Render with an offset to the middle of the list and a selected item
+        group.bench_with_input(
+            BenchmarkId::new("render_scroll_half", line_count),
+            &List::new(lines.clone()).highlight_symbol(">>"),
+            |b, list| {
+                render_stateful(
+                    b,
+                    list,
+                    ListState::default()
+                        .with_offset(line_count / 2)
+                        .with_selected(Some(line_count / 2)),
+                )
+            },
+        );
+    }
+
+    group.finish();
+}
+
+/// render the list into a common size buffer
+fn render(bencher: &mut Bencher, list: &List) {
+    let mut buffer = Buffer::empty(Rect::new(0, 0, 200, 50));
+    // We use `iter_batched` to clone the value in the setup function.
+    // See https://github.com/ratatui-org/ratatui/pull/377.
+    bencher.iter_batched(
+        || list.to_owned(),
+        |bench_list| {
+            Widget::render(bench_list, buffer.area, &mut buffer);
+        },
+        BatchSize::LargeInput,
+    )
+}
+
+/// render the list into a common size buffer with a state
+fn render_stateful(bencher: &mut Bencher, list: &List, mut state: ListState) {
+    let mut buffer = Buffer::empty(Rect::new(0, 0, 200, 50));
+    // We use `iter_batched` to clone the value in the setup function.
+    // See https://github.com/ratatui-org/ratatui/pull/377.
+    bencher.iter_batched(
+        || list.to_owned(),
+        |bench_list| {
+            StatefulWidget::render(bench_list, buffer.area, &mut buffer, &mut state);
+        },
+        BatchSize::LargeInput,
+    )
+}
+
+criterion_group!(benches, list);
+criterion_main!(benches);
--- a/benches/paragraph.rs
+++ b/benches/paragraph.rs
@@ -0,0 +1,97 @@
+use criterion::{
+    black_box, criterion_group, criterion_main, BatchSize, Bencher, BenchmarkId, Criterion,
+};
+use ratatui::{
+    buffer::Buffer,
+    layout::Rect,
+    widgets::{Paragraph, Widget, Wrap},
+};
+
+/// because the scroll offset is a u16, the maximum number of lines that can be scrolled is 65535.
+/// This is a limitation of the current implementation and may be fixed by changing the type of the
+/// scroll offset to a u32.
+const MAX_SCROLL_OFFSET: u16 = u16::MAX;
+const NO_WRAP_WIDTH: u16 = 200;
+const WRAP_WIDTH: u16 = 100;
+
+/// Benchmark for rendering a paragraph with a given number of lines. The design of this benchmark
+/// allows comparison of the performance of rendering a paragraph with different numbers of lines.
+/// as well as comparing with the various settings on the scroll and wrap features.
+pub fn paragraph(c: &mut Criterion) {
+    let mut group = c.benchmark_group("paragraph");
+    for &line_count in [64, 2048, MAX_SCROLL_OFFSET].iter() {
+        let lines = random_lines(line_count);
+        let lines = lines.as_str();
+
+        // benchmark that measures the overhead of creating a paragraph separately from rendering
+        group.bench_with_input(BenchmarkId::new("new", line_count), lines, |b, lines| {
+            b.iter(|| Paragraph::new(black_box(lines)))
+        });
+
+        // render the paragraph with no scroll
+        group.bench_with_input(
+            BenchmarkId::new("render", line_count),
+            &Paragraph::new(lines),
+            |bencher, paragraph| render(bencher, paragraph, NO_WRAP_WIDTH),
+        );
+
+        // scroll the paragraph by half the number of lines and render
+        group.bench_with_input(
+            BenchmarkId::new("render_scroll_half", line_count),
+            &Paragraph::new(lines).scroll((0u16, line_count / 2)),
+            |bencher, paragraph| render(bencher, paragraph, NO_WRAP_WIDTH),
+        );
+
+        // scroll the paragraph by the full number of lines and render
+        group.bench_with_input(
+            BenchmarkId::new("render_scroll_full", line_count),
+            &Paragraph::new(lines).scroll((0u16, line_count)),
+            |bencher, paragraph| render(bencher, paragraph, NO_WRAP_WIDTH),
+        );
+
+        // render the paragraph wrapped to 100 characters
+        group.bench_with_input(
+            BenchmarkId::new("render_wrap", line_count),
+            &Paragraph::new(lines).wrap(Wrap { trim: false }),
+            |bencher, paragraph| render(bencher, paragraph, WRAP_WIDTH),
+        );
+
+        // scroll the paragraph by the full number of lines and render wrapped to 100 characters
+        group.bench_with_input(
+            BenchmarkId::new("render_wrap_scroll_full", line_count),
+            &Paragraph::new(lines)
+                .wrap(Wrap { trim: false })
+                .scroll((0u16, line_count)),
+            |bencher, paragraph| render(bencher, paragraph, WRAP_WIDTH),
+        );
+    }
+    group.finish();
+}
+
+/// render the paragraph into a buffer with the given width
+fn render(bencher: &mut Bencher, paragraph: &Paragraph, width: u16) {
+    let mut buffer = Buffer::empty(Rect::new(0, 0, width, 50));
+    // We use `iter_batched` to clone the value in the setup function.
+    // See https://github.com/ratatui-org/ratatui/pull/377.
+    bencher.iter_batched(
+        || paragraph.to_owned(),
+        |bench_paragraph| {
+            bench_paragraph.render(buffer.area, &mut buffer);
+        },
+        BatchSize::LargeInput,
+    )
+}
+
+/// Create a string with the given number of lines filled with nonsense words
+///
+/// English language has about 5.1 average characters per word so including the space between words
+/// this should emit around 200 characters per paragraph on average.
+fn random_lines(count: u16) -> String {
+    let count = count as i64;
+    let sentence_count = 3;
+    let word_count = 11;
+    fakeit::words::paragraph(count, sentence_count, word_count, "\n".into())
+}
+
+criterion_group!(benches, paragraph);
+criterion_main!(benches);
--- a/benches/sparkline.rs
+++ b/benches/sparkline.rs
@@ -0,0 +1,45 @@
+use criterion::{criterion_group, criterion_main, Bencher, BenchmarkId, Criterion};
+use rand::Rng;
+use ratatui::{
+    buffer::Buffer,
+    layout::Rect,
+    widgets::{Sparkline, Widget},
+};
+
+/// Benchmark for rendering a sparkline.
+pub fn sparkline(c: &mut Criterion) {
+    let mut group = c.benchmark_group("sparkline");
+    let mut rng = rand::thread_rng();
+
+    for data_count in [64, 256, 2048] {
+        let data: Vec<u64> = (0..data_count)
+            .map(|_| rng.gen_range(0..data_count))
+            .collect();
+
+        // Render a basic sparkline
+        group.bench_with_input(
+            BenchmarkId::new("render", data_count),
+            &Sparkline::default().data(&data),
+            render,
+        );
+    }
+
+    group.finish();
+}
+
+/// render the block into a buffer of the given `size`
+fn render(bencher: &mut Bencher, sparkline: &Sparkline) {
+    let mut buffer = Buffer::empty(Rect::new(0, 0, 200, 50));
+    // We use `iter_batched` to clone the value in the setup function.
+    // See https://github.com/ratatui-org/ratatui/pull/377.
+    bencher.iter_batched(
+        || sparkline.clone(),
+        |bench_sparkline| {
+            bench_sparkline.render(buffer.area, &mut buffer);
+        },
+        criterion::BatchSize::LargeInput,
+    )
+}
+
+criterion_group!(benches, sparkline);
+criterion_main!(benches);
--- a/cliff.toml
+++ b/cliff.toml
@@ -0,0 +1,107 @@
+# configuration for https://github.com/orhun/git-cliff
+
+[changelog]
+# changelog header
+header = """
+# Changelog
+
+All notable changes to this project will be documented in this file.
+"""
+# template for the changelog body
+# https://keats.github.io/tera/docs/#introduction
+# note that the - before / after the % controls whether whitespace is rendered between each line.
+# Getting this right so that the markdown renders with the correct number of lines between headings
+# code fences and list items is pretty finicky. Note also that the 4 backticks in the commit macro
+# is intentional as this escapes any backticks in the commit body.
+body = """
+{%- if not version %}
+## [unreleased]
+{% else -%}
+## [{{ version }}](https://github.com/ratatui-org/ratatui/releases/tag/{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }}
+{% endif -%}
+
+{% macro commit(commit) -%}
+- [{{ commit.id | truncate(length=7, end="") }}]({{ "https://github.com/ratatui-org/ratatui/commit/" ~ commit.id }})
+  *({{commit.scope | default(value = "uncategorized") | lower }})* {{ commit.message | upper_first }}
+{%- if commit.breaking %} [**breaking**]{% endif %}
+{%- if commit.body %}
+
+  ````text {#- 4 backticks escape any backticks in body #}
+  {{commit.body | indent(prefix="  ") }}
+  ````
+{%- endif %}
+{% endmacro -%}
+
+{% for group, commits in commits | group_by(attribute="group") %}
+### {{ group | striptags | trim | upper_first }}
+{% for commit in commits | filter(attribute="scope") | sort(attribute="scope") %}
+{{ self::commit(commit=commit) }}
+{%- endfor -%}
+{% for commit in commits %}
+{%- if not commit.scope %}
+{{ self::commit(commit=commit) }}
+{%- endif -%}
+{%- endfor -%}
+{%- endfor %}
+"""
+
+
+# remove the leading and trailing whitespace from the template
+trim = false
+# changelog footer
+footer = """
+<!-- generated by git-cliff -->
+"""
+
+[git]
+# parse the commits based on https://www.conventionalcommits.org
+conventional_commits = true
+# filter out the commits that are not conventional
+filter_unconventional = true
+# process each line of a commit as an individual commit
+split_commits = false
+# regex for preprocessing the commit messages
+commit_preprocessors = [
+  { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](https://github.com/ratatui-org/ratatui/issues/${2}))" },
+  { pattern = '(better safe shared layout cache)', replace = "perf(layout): ${1}" },
+  { pattern = '(Clarify README.md)', replace = "docs(readme): ${1}" },
+  { pattern = '(Update README.md)', replace = "docs(readme): ${1}" },
+  { pattern = '(fix typos|Fix typos)', replace = "fix: ${1}" },
+]
+# regex for parsing and grouping commits
+commit_parsers = [
+  { message = "^feat", group = "<!-- 00 -->Features" },
+  { message = "^[fF]ix", group = "<!-- 01 -->Bug Fixes" },
+  { message = "^refactor", group = "<!-- 02 -->Refactor" },
+  { message = "^doc", group = "<!-- 03 -->Documentation" },
+  { message = "^perf", group = "<!-- 04 -->Performance" },
+  { message = "^style", group = "<!-- 05 -->Styling" },
+  { message = "^test", group = "<!-- 06 -->Testing" },
+  { message = "^chore\\(release\\): prepare for", skip = true },
+  { message = "^chore\\(pr\\)", skip = true },
+  { message = "^chore\\(pull\\)", skip = true },
+  { message = "^chore\\(deps\\)", skip = true },
+  { message = "^chore\\(changelog\\)", skip = true },
+  { message = "^[cC]hore", group = "<!-- 07 -->Miscellaneous Tasks" },
+  { body = ".*security", group = "<!-- 08 -->Security" },
+  { message = "^build", group = "<!-- 09 -->Build" },
+  { message = "^ci", group = "<!-- 10 -->Continuous Integration" },
+  { message = "^revert", group = "<!-- 11 -->Reverted Commits" },
+  # handle some old commits styles from pre 0.4
+  { message = "^(Buffer|buffer|Frame|frame|Gauge|gauge|Paragraph|paragraph):", group = "<!-- 07 -->Miscellaneous Tasks" },
+  { message = "^\\[", group = "<!-- 07 -->Miscellaneous Tasks" },
+]
+# protect breaking changes from being skipped due to matching a skipping commit_parser
+protect_breaking_commits = false
+# filter out the commits that are not matched by commit parsers
+filter_commits = false
+# glob pattern for matching git tags
+tag_pattern = "v[0-9]*"
+# regex for skipping tags
+skip_tags = "v0.1.0-rc.1"
+# regex for ignoring tags
+ignore_tags = "alpha"
+# sort the tags topologically
+topo_order = false
+# sort the commits inside sections by oldest/newest order
+sort_commits = "newest"
--- a/codecov.yml
+++ b/codecov.yml
@@ -0,0 +1,14 @@
+coverage: # https://docs.codecov.com/docs/codecovyml-reference#coverage
+  precision: 1 # e.g. 89.1%
+  round: down
+  range: 85..100 # https://docs.codecov.com/docs/coverage-configuration#section-range
+  status: # https://docs.codecov.com/docs/commit-status
+    project:
+      default:
+        threshold: 1% # Avoid false negatives
+ignore:
+  - "examples"
+  - "benches"
+comment: # https://docs.codecov.com/docs/pull-request-comments
+  # make the comments less noisy
+  require_changes: true
--- a/committed.toml
+++ b/committed.toml
@@ -0,0 +1,30 @@
+# configuration for https://github.com/crate-ci/committed
+
+# https://www.conventionalcommits.org
+style = "conventional"
+# disallow merge commits
+merge_commit = false
+# subject is not required to be capitalized
+subject_capitalized = false
+# subject should start with an imperative verb
+imperative_subject = true
+# subject should not end with a punctuation
+subject_not_punctuated = true
+# disable line length
+line_length = 0
+# disable subject length
+subject_length = 0
+# default allowed_types [ "chore", "docs", "feat", "fix", "perf", "refactor", "style", "test" ]
+allowed_types = [
+  "build",
+  "chore",
+  "ci",
+  "docs",
+  "feat",
+  "fix",
+  "perf",
+  "refactor",
+  "revert",
+  "style",
+  "test",
+]
--- a/deny.toml
+++ b/deny.toml
@@ -0,0 +1,28 @@
+# configuration for https://github.com/EmbarkStudios/cargo-deny
+
+[licenses]
+default = "deny"
+unlicensed = "deny"
+copyleft = "deny"
+confidence-threshold = 0.8
+allow = [
+    "Apache-2.0",
+    "BSD-2-Clause",
+    "BSD-3-Clause",
+    "ISC",
+    "MIT",
+    "Unicode-DFS-2016",
+    "WTFPL",
+]
+
+[advisories]
+unmaintained = "deny"
+yanked = "deny"
+
+[bans]
+multiple-versions = "allow"
+
+[sources]
+unknown-registry = "deny"
+unknown-git = "warn"
+allow-registry = ["https://github.com/rust-lang/crates.io-index"]
--- a/docs/demo.gif
+++ b/docs/demo.gif
--- a/examples/README.md
+++ b/examples/README.md
@@ -0,0 +1,316 @@
+# Examples
+
+These gifs were created using [VHS](https://github.com/charmbracelet/vhs). Each example has a
+corresponding `.tape` file that holds instructions for how to generate the images. Note that the
+images themselves are stored in a separate git branch to avoid bloating the main repository.
+
+## Demo2
+
+This is the demo example from the main README and crate page. Source: [demo2](./demo2/).
+
+```shell
+cargo run --example=demo2 --features="crossterm widget-calendar"
+```
+
+![Demo2][demo2.gif]
+
+## Demo
+
+This is the previous demo example from the main README. It is available for each of the backends. Source:
+[demo.rs](./demo/).
+
+```shell
+cargo run --example=demo --features=crossterm
+cargo run --example=demo --no-default-features --features=termion
+cargo run --example=demo --no-default-features --features=termwiz
+```
+
+![Demo][demo.gif]
+
+## Hello World
+
+This is a pretty boring example, but it contains some good documentation
+on writing tui apps. Source: [hello_world.rs](./hello_world.rs).
+
+```shell
+cargo run --example=hello_world --features=crossterm
+```
+
+![Hello World][hello_world.gif]
+
+## Barchart
+
+Demonstrates the [`BarChart`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.BarChart.html)
+widget. Source: [barchart.rs](./barchart.rs).
+
+```shell
+cargo run --example=barchart --features=crossterm
+```
+
+![Barchart][barchart.gif]
+
+## Block
+
+Demonstrates the [`Block`](https://docs.rs/ratatui/latest/ratatui/widgets/block/struct.Block.html)
+widget. Source: [block.rs](./block.rs).
+
+```shell
+cargo run --example=block --features=crossterm
+```
+
+![Block][block.gif]
+
+## Calendar
+
+Demonstrates the [`Calendar`](https://docs.rs/ratatui/latest/ratatui/widgets/calendar/index.html)
+widget. Source: [calendar.rs](./calendar.rs).
+
+```shell
+cargo run --example=calendar --features="crossterm widget-calendar"
+```
+
+![Calendar][calendar.gif]
+
+## Canvas
+
+Demonstrates the [`Canvas`](https://docs.rs/ratatui/latest/ratatui/widgets/canvas/index.html) widget
+and related shapes in the
+[`canvas`](https://docs.rs/ratatui/latest/ratatui/widgets/canvas/index.html) module. Source:
+[canvas.rs](./canvas.rs).
+
+```shell
+cargo run --example=canvas --features=crossterm
+```
+
+![Canvas][canvas.gif]
+
+## Chart
+
+Demonstrates the [`Chart`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Chart.html) widget.
+Source: [chart.rs](./chart.rs).
+
+```shell
+cargo run --example=chart --features=crossterm
+```
+
+![Chart][chart.gif]
+
+## Colors
+
+Demonstrates the available [`Color`](https://docs.rs/ratatui/latest/ratatui/style/enum.Color.html)
+options. These can be used in any style field. Source: [colors.rs](./colors.rs).
+
+```shell
+cargo run --example=colors --features=crossterm
+```
+
+![Colors][colors.gif]
+
+## Colors (RGB)
+
+Demonstrates the available RGB
+[`Color`](https://docs.rs/ratatui/latest/ratatui/style/enum.Color.html) options. These can be used
+in any style field. Source: [colors_rgb.rs](./colors_rgb.rs). Uses a half block technique to render
+two square-ish pixels in the space of a single rectangular terminal cell.
+
+```shell
+cargo run --example=colors_rgb --features=crossterm
+```
+
+![Colors RGB][colors_rgb.png]
+
+## Custom Widget
+
+Demonstrates how to implement the
+[`Widget`](https://docs.rs/ratatui/latest/ratatui/widgets/trait.Widget.html) trait. Also shows mouse
+interaction. Source: [custom_widget.rs](./custom_widget.rs).
+
+```shell
+cargo run --example=custom_widget --features=crossterm
+```
+
+![Custom Widget][custom_widget.gif]
+
+## Gauge
+
+Demonstrates the [`Gauge`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Gauge.html) widget.
+Source: [gauge.rs](./gauge.rs).
+
+```shell
+cargo run --example=gauge --features=crossterm
+```
+
+![Gauge][gauge.gif]
+
+## Inline
+
+Demonstrates how to use the
+[`Inline`](https://docs.rs/ratatui/latest/ratatui/terminal/enum.Viewport.html#variant.Inline)
+Viewport mode for ratatui apps. Source: [inline.rs](./inline.rs).
+
+```shell
+cargo run --example=inline --features=crossterm
+```
+
+![Inline][inline.gif]
+
+## Layout
+
+Demonstrates the [`Layout`](https://docs.rs/ratatui/latest/ratatui/layout/struct.Layout.html) and
+interaction between each constraint. Source:  [layout.rs](./layout.rs).
+
+```shell
+cargo run --example=layout --features=crossterm
+```
+
+![Layout][layout.gif]
+
+## List
+
+Demonstrates the [`List`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.List.html) widget.
+Source: [list.rs](./list.rs).
+
+```shell
+cargo run --example=list --features=crossterm
+```
+
+![List][list.gif]
+
+## Modifiers
+
+Demonstrates the style
+[`Modifiers`](https://docs.rs/ratatui/latest/ratatui/style/struct.Modifier.html). Source:
+[modifiers.rs](./modifiers.rs).
+
+```shell
+cargo run --example=modifiers --features=crossterm
+```
+
+![Modifiers][modifiers.gif]
+
+## Panic
+
+Demonstrates how to handle panics by ensuring that panic messages are written correctly to the
+screen. Source: [panic.rs](./panic.rs).
+
+```shell
+cargo run --example=panic --features=crossterm
+```
+
+![Panic][panic.gif]
+
+## Paragraph
+
+Demonstrates the [`Paragraph`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Paragraph.html)
+widget. Source: [paragraph.rs](./paragraph.rs)
+
+```shell
+cargo run --example=paragraph --features=crossterm
+```
+
+![Paragraph][paragraph.gif]
+
+## Popup
+
+Demonstrates how to render a widget over the top of previously rendered widgets using the
+[`Clear`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Clear.html) widget. Source:
+[popup.rs](./popup.rs).
+
+>
+```shell
+cargo run --example=popup --features=crossterm
+```
+
+![Popup][popup.gif]
+
+## Scrollbar
+
+Demonstrates the [`Scrollbar`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Scrollbar.html)
+widget. Source: [scrollbar.rs](./scrollbar.rs).
+
+```shell
+cargo run --example=scrollbar --features=crossterm
+```
+
+![Scrollbar][scrollbar.gif]
+
+## Sparkline
+
+Demonstrates the [`Sparkline`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Sparkline.html)
+widget. Source: [sparkline.rs](./sparkline.rs).
+
+```shell
+cargo run --example=sparkline --features=crossterm
+```
+
+![Sparkline][sparkline.gif]
+
+## Table
+
+Demonstrates the [`Table`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Table.html) widget.
+Source: [table.rs](./table.rs).
+
+```shell
+cargo run --example=table --features=crossterm
+```
+
+![Table][table.gif]
+
+## Tabs
+
+Demonstrates the [`Tabs`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Tabs.html) widget.
+Source: [tabs.rs](./tabs.rs).
+
+```shell
+cargo run --example=tabs --features=crossterm
+```
+
+![Tabs][tabs.gif]
+
+## User Input
+
+Demonstrates one approach to accepting user input. Source [user_input.rs](./user_input.rs).
+
+> [!NOTE] Consider using [`tui-textarea`](https://crates.io/crates/tui-textarea) or
+> [`tui-input`](https://crates.io/crates/tui-input) crates for more functional text entry UIs.
+
+```shell
+cargo run --example=user_input --features=crossterm
+```
+
+![User Input][user_input.gif]
+
+<!--
+links to images to make it easier to update in bulk
+These are generated with `vhs publish examples/xxx.gif`
+
+To update these examples in bulk:
+```shell
+examples/generate.bash
+```
+-->
+
+[barchart.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/barchart.gif?raw=true
+[block.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/block.gif?raw=true
+[calendar.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/calendar.gif?raw=true
+[canvas.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/canvas.gif?raw=true
+[chart.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/chart.gif?raw=true
+[colors.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/colors.gif?raw=true
+[colors_rgb.png]: https://github.com/ratatui-org/ratatui/blob/images/examples/colors_rgb.png?raw=true
+[custom_widget.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/custom_widget.gif?raw=true
+[demo.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/demo.gif?raw=true
+[demo2.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/demo2.gif?raw=true
+[gauge.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/gauge.gif?raw=true
+[hello_world.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/hello_world.gif?raw=true
+[inline.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/inline.gif?raw=true
+[layout.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/layout.gif?raw=true
+[list.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/list.gif?raw=true
+[modifiers.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/modifiers.gif?raw=true
+[panic.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/panic.gif?raw=true
+[paragraph.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/paragraph.gif?raw=true
+[popup.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/popup.gif?raw=true
+[scrollbar.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/scrollbar.gif?raw=true
+[sparkline.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/sparkline.gif?raw=true
+[table.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/table.gif?raw=true
+[tabs.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/tabs.gif?raw=true
+[user_input.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/user_input.gif?raw=true
--- a/examples/barchart.rs
+++ b/examples/barchart.rs
@@ -1,29 +1,33 @@
-extern crate termion;
-extern crate tui;
+use std::{
+    error::Error,
+    io,
+    time::{Duration, Instant},
+};

-use std::io;
-use std::sync::mpsc;
-use std::thread;
-use std::time;
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{prelude::*, widgets::*};

-use termion::event;
-use termion::input::TermRead;
-
-use tui::backend::MouseBackend;
-use tui::layout::{Constraint, Direction, Layout, Rect};
-use tui::style::{Color, Modifier, Style};
-use tui::widgets::{BarChart, Block, Borders, Widget};
-use tui::Terminal;
+struct Company<'a> {
+    revenue: [u64; 4],
+    label: &'a str,
+    bar_style: Style,
+}

 struct App<'a> {
-    size: Rect,
    data: Vec<(&'a str, u64)>,
+    months: [&'a str; 4],
+    companies: [Company<'a>; 3],
 }

+const TOTAL_REVENUE: &str = "Total Revenue";
+
 impl<'a> App<'a> {
    fn new() -> App<'a> {
        App {
-            size: Rect::default(),
            data: vec![
                ("B1", 9),
                ("B2", 12),
@@ -50,115 +54,229 @@ impl<'a> App<'a> {
                ("B23", 3),
                ("B24", 5),
            ],
+            companies: [
+                Company {
+                    label: "Comp.A",
+                    revenue: [9500, 12500, 5300, 8500],
+                    bar_style: Style::default().fg(Color::Green),
+                },
+                Company {
+                    label: "Comp.B",
+                    revenue: [1500, 2500, 3000, 500],
+                    bar_style: Style::default().fg(Color::Yellow),
+                },
+                Company {
+                    label: "Comp.C",
+                    revenue: [10500, 10600, 9000, 4200],
+                    bar_style: Style::default().fg(Color::White),
+                },
+            ],
+            months: ["Mars", "Apr", "May", "Jun"],
        }
    }

-    fn advance(&mut self) {
+    fn on_tick(&mut self) {
        let value = self.data.pop().unwrap();
        self.data.insert(0, value);
    }
 }

-enum Event {
-    Input(event::Key),
-    Tick,
-}
+fn main() -> Result<(), Box<dyn Error>> {
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;

-fn main() {
-    // Terminal initialization
-    let backend = MouseBackend::new().unwrap();
-    let mut terminal = Terminal::new(backend).unwrap();
+    // create app and run it
+    let tick_rate = Duration::from_millis(250);
+    let app = App::new();
+    let res = run_app(&mut terminal, app, tick_rate);

-    // Channels
-    let (tx, rx) = mpsc::channel();
-    let input_tx = tx.clone();
-    let clock_tx = tx.clone();
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;

-    // Input
-    thread::spawn(move || {
-        let stdin = io::stdin();
-        for c in stdin.keys() {
-            let evt = c.unwrap();
-            input_tx.send(Event::Input(evt)).unwrap();
-            if evt == event::Key::Char('q') {
-                break;
-            }
-        }
-    });
-
-    // Tick
-    thread::spawn(move || loop {
-        clock_tx.send(Event::Tick).unwrap();
-        thread::sleep(time::Duration::from_millis(500));
-    });
-
-    // App
-    let mut app = App::new();
-
-    // First draw call
-    terminal.clear().unwrap();
-    terminal.hide_cursor().unwrap();
-    app.size = terminal.size().unwrap();
-    draw(&mut terminal, &app).unwrap();
-
-    loop {
-        let size = terminal.size().unwrap();
-        if app.size != size {
-            terminal.resize(size).unwrap();
-            app.size = size;
-        }
-
-        let evt = rx.recv().unwrap();
-        match evt {
-            Event::Input(input) => if input == event::Key::Char('q') {
-                break;
-            },
-            Event::Tick => {
-                app.advance();
-            }
-        }
-        draw(&mut terminal, &app).unwrap();
+    if let Err(err) = res {
+        println!("{err:?}");
    }

-    terminal.show_cursor().unwrap();
+    Ok(())
 }

-fn draw(t: &mut Terminal<MouseBackend>, app: &App) -> Result<(), io::Error> {
-    t.draw(|mut f| {
-        let chunks = Layout::default()
-            .direction(Direction::Vertical)
-            .margin(2)
-            .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-            .split(app.size);
-        BarChart::default()
-            .block(Block::default().title("Data1").borders(Borders::ALL))
-            .data(&app.data)
-            .bar_width(9)
-            .style(Style::default().fg(Color::Yellow))
-            .value_style(Style::default().fg(Color::Black).bg(Color::Yellow))
-            .render(&mut f, chunks[0]);
-        {
-            let chunks = Layout::default()
-                .direction(Direction::Horizontal)
-                .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-                .split(chunks[1]);
-            BarChart::default()
-                .block(Block::default().title("Data2").borders(Borders::ALL))
-                .data(&app.data)
-                .bar_width(5)
-                .bar_gap(3)
-                .style(Style::default().fg(Color::Green))
-                .value_style(Style::default().bg(Color::Green).modifier(Modifier::Bold))
-                .render(&mut f, chunks[0]);
-            BarChart::default()
-                .block(Block::default().title("Data3").borders(Borders::ALL))
-                .data(&app.data)
-                .style(Style::default().fg(Color::Red))
-                .bar_width(7)
-                .bar_gap(0)
-                .value_style(Style::default().bg(Color::Red))
-                .label_style(Style::default().fg(Color::Cyan).modifier(Modifier::Italic))
-                .render(&mut f, chunks[1]);
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    mut app: App,
+    tick_rate: Duration,
+) -> io::Result<()> {
+    let mut last_tick = Instant::now();
+    loop {
+        terminal.draw(|f| ui(f, &app))?;
+
+        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+        if crossterm::event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                if let KeyCode::Char('q') = key.code {
+                    return Ok(());
+                }
+            }
        }
-    })
+        if last_tick.elapsed() >= tick_rate {
+            app.on_tick();
+            last_tick = Instant::now();
+        }
+    }
+}
+
+fn ui(f: &mut Frame, app: &App) {
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Ratio(1, 3), Constraint::Ratio(2, 3)])
+        .split(f.size());
+
+    let barchart = BarChart::default()
+        .block(Block::default().title("Data1").borders(Borders::ALL))
+        .data(&app.data)
+        .bar_width(9)
+        .bar_style(Style::default().fg(Color::Yellow))
+        .value_style(Style::default().fg(Color::Black).bg(Color::Yellow));
+    f.render_widget(barchart, chunks[0]);
+
+    let chunks = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
+        .split(chunks[1]);
+
+    draw_bar_with_group_labels(f, app, chunks[0]);
+    draw_horizontal_bars(f, app, chunks[1]);
+}
+
+fn create_groups<'a>(app: &'a App, combine_values_and_labels: bool) -> Vec<BarGroup<'a>> {
+    app.months
+        .iter()
+        .enumerate()
+        .map(|(i, &month)| {
+            let bars: Vec<Bar> = app
+                .companies
+                .iter()
+                .map(|c| {
+                    let mut bar = Bar::default()
+                        .value(c.revenue[i])
+                        .style(c.bar_style)
+                        .value_style(
+                            Style::default()
+                                .bg(c.bar_style.fg.unwrap())
+                                .fg(Color::Black),
+                        );
+
+                    if combine_values_and_labels {
+                        bar = bar.text_value(format!(
+                            "{} ({:.1} M)",
+                            c.label,
+                            (c.revenue[i] as f64) / 1000.
+                        ));
+                    } else {
+                        bar = bar
+                            .text_value(format!("{:.1}", (c.revenue[i] as f64) / 1000.))
+                            .label(c.label.into());
+                    }
+                    bar
+                })
+                .collect();
+            BarGroup::default()
+                .label(Line::from(month).alignment(Alignment::Center))
+                .bars(&bars)
+        })
+        .collect()
+}
+
+fn draw_bar_with_group_labels(f: &mut Frame, app: &App, area: Rect) {
+    let groups = create_groups(app, false);
+
+    let mut barchart = BarChart::default()
+        .block(Block::default().title("Data1").borders(Borders::ALL))
+        .bar_width(7)
+        .group_gap(3);
+
+    for group in groups {
+        barchart = barchart.data(group)
+    }
+
+    f.render_widget(barchart, area);
+
+    const LEGEND_HEIGHT: u16 = 6;
+    if area.height >= LEGEND_HEIGHT && area.width >= TOTAL_REVENUE.len() as u16 + 2 {
+        let legend_width = TOTAL_REVENUE.len() as u16 + 2;
+        let legend_area = Rect {
+            height: LEGEND_HEIGHT,
+            width: legend_width,
+            y: area.y,
+            x: area.right() - legend_width,
+        };
+        draw_legend(f, legend_area);
+    }
+}
+
+fn draw_horizontal_bars(f: &mut Frame, app: &App, area: Rect) {
+    let groups = create_groups(app, true);
+
+    let mut barchart = BarChart::default()
+        .block(Block::default().title("Data1").borders(Borders::ALL))
+        .bar_width(1)
+        .group_gap(1)
+        .bar_gap(0)
+        .direction(Direction::Horizontal);
+
+    for group in groups {
+        barchart = barchart.data(group)
+    }
+
+    f.render_widget(barchart, area);
+
+    const LEGEND_HEIGHT: u16 = 6;
+    if area.height >= LEGEND_HEIGHT && area.width >= TOTAL_REVENUE.len() as u16 + 2 {
+        let legend_width = TOTAL_REVENUE.len() as u16 + 2;
+        let legend_area = Rect {
+            height: LEGEND_HEIGHT,
+            width: legend_width,
+            y: area.y,
+            x: area.right() - legend_width,
+        };
+        draw_legend(f, legend_area);
+    }
+}
+
+fn draw_legend(f: &mut Frame, area: Rect) {
+    let text = vec![
+        Line::from(Span::styled(
+            TOTAL_REVENUE,
+            Style::default()
+                .add_modifier(Modifier::BOLD)
+                .fg(Color::White),
+        )),
+        Line::from(Span::styled(
+            "- Company A",
+            Style::default().fg(Color::Green),
+        )),
+        Line::from(Span::styled(
+            "- Company B",
+            Style::default().fg(Color::Yellow),
+        )),
+        Line::from(vec![Span::styled(
+            "- Company C",
+            Style::default().fg(Color::White),
+        )]),
+    ];
+
+    let block = Block::default()
+        .borders(Borders::ALL)
+        .style(Style::default().fg(Color::White));
+    let paragraph = Paragraph::new(text).block(block);
+    f.render_widget(paragraph, area);
 }
--- a/examples/barchart.tape
+++ b/examples/barchart.tape
@@ -0,0 +1,12 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/barchart.tape`
+Output "target/barchart.gif"
+Set Theme "Aardvark Blue"
+Set Width 1200
+Set Height 800
+Hide
+Type "cargo run --example=barchart"
+Enter
+Sleep 1s
+Show
+Sleep 5s
--- a/examples/block.rs
+++ b/examples/block.rs
@@ -1,84 +1,252 @@
-extern crate termion;
-extern crate tui;
+use std::{
+    error::Error,
+    io::{stdout, Stdout},
+    ops::ControlFlow,
+    time::Duration,
+};

-use std::io;
-use termion::event;
-use termion::input::TermRead;
+use crossterm::{
+    event::{self, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use itertools::Itertools;
+use ratatui::{
+    prelude::*,
+    widgets::{
+        block::{Position, Title},
+        Block, BorderType, Borders, Padding, Paragraph, Wrap,
+    },
+};

-use tui::backend::MouseBackend;
-use tui::layout::{Constraint, Direction, Layout, Rect};
-use tui::style::{Color, Modifier, Style};
-use tui::widgets::{Block, Borders, Widget};
-use tui::Terminal;
+// These type aliases are used to make the code more readable by reducing repetition of the generic
+// types. They are not necessary for the functionality of the code.
+type Terminal = ratatui::Terminal<CrosstermBackend<Stdout>>;
+type Result<T> = std::result::Result<T, Box<dyn Error>>;

-fn main() {
-    let mut terminal = Terminal::new(MouseBackend::new().unwrap()).unwrap();
-    let stdin = io::stdin();
-    terminal.clear().unwrap();
-    terminal.hide_cursor().unwrap();
+fn main() -> Result<()> {
+    let mut terminal = setup_terminal()?;
+    let result = run(&mut terminal);
+    restore_terminal(terminal)?;

-    let mut term_size = terminal.size().unwrap();
-    draw(&mut terminal, term_size).unwrap();
-    for c in stdin.keys() {
-        let size = terminal.size().unwrap();
-        if term_size != size {
-            terminal.resize(size).unwrap();
-            term_size = size;
-        }
-        draw(&mut terminal, term_size).unwrap();
-        let evt = c.unwrap();
-        if evt == event::Key::Char('q') {
-            break;
+    if let Err(err) = result {
+        eprintln!("{err:?}");
+    }
+    Ok(())
+}
+
+fn setup_terminal() -> Result<Terminal> {
+    enable_raw_mode()?;
+    let mut stdout = stdout();
+    execute!(stdout, EnterAlternateScreen)?;
+    let backend = CrosstermBackend::new(stdout);
+    let terminal = Terminal::new(backend)?;
+    Ok(terminal)
+}
+
+fn restore_terminal(mut terminal: Terminal) -> Result<()> {
+    disable_raw_mode()?;
+    execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
+    Ok(())
+}
+
+fn run(terminal: &mut Terminal) -> Result<()> {
+    loop {
+        terminal.draw(ui)?;
+        if handle_events()?.is_break() {
+            return Ok(());
        }
    }
-    terminal.show_cursor().unwrap();
 }

-fn draw(t: &mut Terminal<MouseBackend>, size: Rect) -> Result<(), io::Error> {
-    t.draw(|mut f| {
-        // Wrapping block for a group
-        // Just draw the block and the group on the same area and build the group
-        // with at least a margin of 1
-        Block::default().borders(Borders::ALL).render(&mut f, size);
-        let chunks = Layout::default()
-            .direction(Direction::Vertical)
-            .margin(4)
-            .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-            .split(size);
-        {
-            let chunks = Layout::default()
-                .direction(Direction::Horizontal)
-                .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-                .split(chunks[0]);
-            Block::default()
-                .title("With background")
-                .title_style(Style::default().fg(Color::Yellow))
-                .style(Style::default().bg(Color::Green))
-                .render(&mut f, chunks[0]);
-            Block::default()
-                .title("Styled title")
-                .title_style(
-                    Style::default()
-                        .fg(Color::White)
-                        .bg(Color::Red)
-                        .modifier(Modifier::Bold),
-                )
-                .render(&mut f, chunks[1]);
+fn handle_events() -> Result<ControlFlow<()>> {
+    if event::poll(Duration::from_millis(100))? {
+        if let Event::Key(key) = event::read()? {
+            if let KeyCode::Char('q') = key.code {
+                return Ok(ControlFlow::Break(()));
+            }
        }
-        {
-            let chunks = Layout::default()
-                .direction(Direction::Horizontal)
-                .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-                .split(chunks[1]);
-            Block::default()
-                .title("With borders")
-                .borders(Borders::ALL)
-                .render(&mut f, chunks[0]);
-            Block::default()
-                .title("With styled borders")
-                .border_style(Style::default().fg(Color::Cyan))
-                .borders(Borders::LEFT | Borders::RIGHT)
-                .render(&mut f, chunks[1]);
-        }
-    })
+    }
+    Ok(ControlFlow::Continue(()))
+}
+
+fn ui(frame: &mut Frame) {
+    let (title_area, layout) = calculate_layout(frame.size());
+
+    render_title(frame, title_area);
+
+    let paragraph = placeholder_paragraph();
+
+    render_borders(&paragraph, Borders::ALL, frame, layout[0][0]);
+    render_borders(&paragraph, Borders::NONE, frame, layout[0][1]);
+    render_borders(&paragraph, Borders::LEFT, frame, layout[1][0]);
+    render_borders(&paragraph, Borders::RIGHT, frame, layout[1][1]);
+    render_borders(&paragraph, Borders::TOP, frame, layout[2][0]);
+    render_borders(&paragraph, Borders::BOTTOM, frame, layout[2][1]);
+
+    render_border_type(&paragraph, BorderType::Plain, frame, layout[3][0]);
+    render_border_type(&paragraph, BorderType::Rounded, frame, layout[3][1]);
+    render_border_type(&paragraph, BorderType::Double, frame, layout[4][0]);
+    render_border_type(&paragraph, BorderType::Thick, frame, layout[4][1]);
+
+    render_styled_block(&paragraph, frame, layout[5][0]);
+    render_styled_borders(&paragraph, frame, layout[5][1]);
+    render_styled_title(&paragraph, frame, layout[6][0]);
+    render_styled_title_content(&paragraph, frame, layout[6][1]);
+    render_multiple_titles(&paragraph, frame, layout[7][0]);
+    render_multiple_title_positions(&paragraph, frame, layout[7][1]);
+    render_padding(&paragraph, frame, layout[8][0]);
+    render_nested_blocks(&paragraph, frame, layout[8][1]);
+}
+
+/// Calculate the layout of the UI elements.
+///
+/// Returns a tuple of the title area and the main areas.
+fn calculate_layout(area: Rect) -> (Rect, Vec<Vec<Rect>>) {
+    let layout = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Length(1), Constraint::Min(0)])
+        .split(area);
+    let title_area = layout[0];
+    let main_areas = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Max(4); 9])
+        .split(layout[1])
+        .iter()
+        .map(|&area| {
+            Layout::default()
+                .direction(Direction::Horizontal)
+                .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
+                .split(area)
+                .to_vec()
+        })
+        .collect_vec();
+    (title_area, main_areas)
+}
+
+fn render_title(frame: &mut Frame, area: Rect) {
+    frame.render_widget(
+        Paragraph::new("Block example. Press q to quit")
+            .dark_gray()
+            .alignment(Alignment::Center),
+        area,
+    );
+}
+
+fn placeholder_paragraph() -> Paragraph<'static> {
+    let text = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.";
+    Paragraph::new(text.dark_gray()).wrap(Wrap { trim: true })
+}
+
+fn render_borders(paragraph: &Paragraph, border: Borders, frame: &mut Frame, area: Rect) {
+    let block = Block::new()
+        .borders(border)
+        .title(format!("Borders::{border:#?}", border = border));
+    frame.render_widget(paragraph.clone().block(block), area);
+}
+
+fn render_border_type(
+    paragraph: &Paragraph,
+    border_type: BorderType,
+    frame: &mut Frame,
+    area: Rect,
+) {
+    let block = Block::new()
+        .borders(Borders::ALL)
+        .border_type(border_type)
+        .title(format!("BorderType::{border_type:#?}"));
+    frame.render_widget(paragraph.clone().block(block), area);
+}
+fn render_styled_borders(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
+    let block = Block::new()
+        .borders(Borders::ALL)
+        .border_style(Style::new().blue().on_white().bold().italic())
+        .title("Styled borders");
+    frame.render_widget(paragraph.clone().block(block), area);
+}
+
+fn render_styled_block(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
+    let block = Block::new()
+        .borders(Borders::ALL)
+        .style(Style::new().blue().on_white().bold().italic())
+        .title("Styled block");
+    frame.render_widget(paragraph.clone().block(block), area);
+}
+
+// Note: this currently renders incorrectly, see https://github.com/ratatui-org/ratatui/issues/349
+fn render_styled_title(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
+    let block = Block::new()
+        .borders(Borders::ALL)
+        .title("Styled title")
+        .title_style(Style::new().blue().on_white().bold().italic());
+    frame.render_widget(paragraph.clone().block(block), area);
+}
+
+fn render_styled_title_content(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
+    let title = Line::from(vec![
+        "Styled ".blue().on_white().bold().italic(),
+        "title content".red().on_white().bold().italic(),
+    ]);
+    let block = Block::new().borders(Borders::ALL).title(title);
+    frame.render_widget(paragraph.clone().block(block), area);
+}
+
+fn render_multiple_titles(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
+    let block = Block::new()
+        .borders(Borders::ALL)
+        .title("Multiple".blue().on_white().bold().italic())
+        .title("Titles".red().on_white().bold().italic());
+    frame.render_widget(paragraph.clone().block(block), area);
+}
+
+fn render_multiple_title_positions(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
+    let block = Block::new()
+        .borders(Borders::ALL)
+        .title(
+            Title::from("top left")
+                .position(Position::Top)
+                .alignment(Alignment::Left),
+        )
+        .title(
+            Title::from("top center")
+                .position(Position::Top)
+                .alignment(Alignment::Center),
+        )
+        .title(
+            Title::from("top right")
+                .position(Position::Top)
+                .alignment(Alignment::Right),
+        )
+        .title(
+            Title::from("bottom left")
+                .position(Position::Bottom)
+                .alignment(Alignment::Left),
+        )
+        .title(
+            Title::from("bottom center")
+                .position(Position::Bottom)
+                .alignment(Alignment::Center),
+        )
+        .title(
+            Title::from("bottom right")
+                .position(Position::Bottom)
+                .alignment(Alignment::Right),
+        );
+    frame.render_widget(paragraph.clone().block(block), area);
+}
+
+fn render_padding(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
+    let block = Block::new()
+        .borders(Borders::ALL)
+        .title("Padding")
+        .padding(Padding::new(5, 10, 1, 2));
+    frame.render_widget(paragraph.clone().block(block), area);
+}
+
+fn render_nested_blocks(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
+    let outer_block = Block::new().borders(Borders::ALL).title("Outer block");
+    let inner_block = Block::new().borders(Borders::ALL).title("Inner block");
+    let inner = outer_block.inner(area);
+    frame.render_widget(outer_block, area);
+    frame.render_widget(paragraph.clone().block(inner_block), inner);
 }
--- a/examples/block.tape
+++ b/examples/block.tape
@@ -0,0 +1,12 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/block.tape`
+Output "target/block.gif"
+Set Theme "Aardvark Blue"
+Set Width 1200
+Set Height 1200
+Hide
+Type "cargo run --example=block"
+Enter
+Sleep 2s
+Show
+Sleep 2s
--- a/examples/calendar.rs
+++ b/examples/calendar.rs
@@ -0,0 +1,271 @@
+use std::{error::Error, io, rc::Rc};
+
+use crossterm::{
+    event::{self, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{prelude::*, widgets::calendar::*};
+use time::{Date, Month, OffsetDateTime};
+
+fn main() -> Result<(), Box<dyn Error>> {
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+
+    loop {
+        let _ = terminal.draw(draw);
+
+        if let Event::Key(key) = event::read()? {
+            #[allow(clippy::single_match)]
+            match key.code {
+                KeyCode::Char(_) => {
+                    break;
+                }
+                _ => {}
+            };
+        }
+    }
+
+    disable_raw_mode()?;
+    execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
+    terminal.show_cursor()?;
+    Ok(())
+}
+
+fn draw(f: &mut Frame) {
+    let app_area = f.size();
+
+    let calarea = Rect {
+        x: app_area.x + 1,
+        y: app_area.y + 1,
+        height: app_area.height - 1,
+        width: app_area.width - 1,
+    };
+
+    let mut start = OffsetDateTime::now_local()
+        .unwrap()
+        .date()
+        .replace_month(Month::January)
+        .unwrap()
+        .replace_day(1)
+        .unwrap();
+
+    let list = make_dates(start.year());
+
+    for chunk in split_rows(&calarea)
+        .iter()
+        .flat_map(|row| split_cols(row).to_vec())
+    {
+        let cal = cals::get_cal(start.month(), start.year(), &list);
+        f.render_widget(cal, chunk);
+        start = start.replace_month(start.month().next()).unwrap();
+    }
+}
+
+fn split_rows(area: &Rect) -> Rc<[Rect]> {
+    let list_layout = Layout::default()
+        .direction(Direction::Vertical)
+        .margin(0)
+        .constraints([
+            Constraint::Percentage(33),
+            Constraint::Percentage(33),
+            Constraint::Percentage(33),
+        ]);
+
+    list_layout.split(*area)
+}
+
+fn split_cols(area: &Rect) -> Rc<[Rect]> {
+    let list_layout = Layout::default()
+        .direction(Direction::Horizontal)
+        .margin(0)
+        .constraints([
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+        ]);
+
+    list_layout.split(*area)
+}
+
+fn make_dates(current_year: i32) -> CalendarEventStore {
+    let mut list = CalendarEventStore::today(
+        Style::default()
+            .add_modifier(Modifier::BOLD)
+            .bg(Color::Blue),
+    );
+
+    // Holidays
+    let holiday_style = Style::default()
+        .fg(Color::Red)
+        .add_modifier(Modifier::UNDERLINED);
+
+    // new year's
+    list.add(
+        Date::from_calendar_date(current_year, Month::January, 1).unwrap(),
+        holiday_style,
+    );
+    // next new_year's for December "show surrounding"
+    list.add(
+        Date::from_calendar_date(current_year + 1, Month::January, 1).unwrap(),
+        holiday_style,
+    );
+    // groundhog day
+    list.add(
+        Date::from_calendar_date(current_year, Month::February, 2).unwrap(),
+        holiday_style,
+    );
+    // april fool's
+    list.add(
+        Date::from_calendar_date(current_year, Month::April, 1).unwrap(),
+        holiday_style,
+    );
+    // earth day
+    list.add(
+        Date::from_calendar_date(current_year, Month::April, 22).unwrap(),
+        holiday_style,
+    );
+    // star wars day
+    list.add(
+        Date::from_calendar_date(current_year, Month::May, 4).unwrap(),
+        holiday_style,
+    );
+    // festivus
+    list.add(
+        Date::from_calendar_date(current_year, Month::December, 23).unwrap(),
+        holiday_style,
+    );
+    // new year's eve
+    list.add(
+        Date::from_calendar_date(current_year, Month::December, 31).unwrap(),
+        holiday_style,
+    );
+
+    // seasons
+    let season_style = Style::default()
+        .fg(Color::White)
+        .bg(Color::Yellow)
+        .add_modifier(Modifier::UNDERLINED);
+    // spring equinox
+    list.add(
+        Date::from_calendar_date(current_year, Month::March, 22).unwrap(),
+        season_style,
+    );
+    // summer solstice
+    list.add(
+        Date::from_calendar_date(current_year, Month::June, 21).unwrap(),
+        season_style,
+    );
+    // fall equinox
+    list.add(
+        Date::from_calendar_date(current_year, Month::September, 22).unwrap(),
+        season_style,
+    );
+    list.add(
+        Date::from_calendar_date(current_year, Month::December, 21).unwrap(),
+        season_style,
+    );
+    list
+}
+
+mod cals {
+    use super::*;
+
+    pub(super) fn get_cal<'a, S: DateStyler>(m: Month, y: i32, es: S) -> Monthly<'a, S> {
+        use Month::*;
+        match m {
+            May => example1(m, y, es),
+            June => example2(m, y, es),
+            July => example3(m, y, es),
+            December => example3(m, y, es),
+            February => example4(m, y, es),
+            November => example5(m, y, es),
+            _ => default(m, y, es),
+        }
+    }
+
+    fn default<'a, S: DateStyler>(m: Month, y: i32, es: S) -> Monthly<'a, S> {
+        let default_style = Style::default()
+            .add_modifier(Modifier::BOLD)
+            .bg(Color::Rgb(50, 50, 50));
+
+        Monthly::new(Date::from_calendar_date(y, m, 1).unwrap(), es)
+            .show_month_header(Style::default())
+            .default_style(default_style)
+    }
+
+    fn example1<'a, S: DateStyler>(m: Month, y: i32, es: S) -> Monthly<'a, S> {
+        let default_style = Style::default()
+            .add_modifier(Modifier::BOLD)
+            .bg(Color::Rgb(50, 50, 50));
+
+        Monthly::new(Date::from_calendar_date(y, m, 1).unwrap(), es)
+            .show_surrounding(default_style)
+            .default_style(default_style)
+            .show_month_header(Style::default())
+    }
+
+    fn example2<'a, S: DateStyler>(m: Month, y: i32, es: S) -> Monthly<'a, S> {
+        let header_style = Style::default()
+            .add_modifier(Modifier::BOLD)
+            .add_modifier(Modifier::DIM)
+            .fg(Color::LightYellow);
+
+        let default_style = Style::default()
+            .add_modifier(Modifier::BOLD)
+            .bg(Color::Rgb(50, 50, 50));
+
+        Monthly::new(Date::from_calendar_date(y, m, 1).unwrap(), es)
+            .show_weekdays_header(header_style)
+            .default_style(default_style)
+            .show_month_header(Style::default())
+    }
+
+    fn example3<'a, S: DateStyler>(m: Month, y: i32, es: S) -> Monthly<'a, S> {
+        let header_style = Style::default()
+            .add_modifier(Modifier::BOLD)
+            .fg(Color::Green);
+
+        let default_style = Style::default()
+            .add_modifier(Modifier::BOLD)
+            .bg(Color::Rgb(50, 50, 50));
+
+        Monthly::new(Date::from_calendar_date(y, m, 1).unwrap(), es)
+            .show_surrounding(Style::default().add_modifier(Modifier::DIM))
+            .show_weekdays_header(header_style)
+            .default_style(default_style)
+            .show_month_header(Style::default())
+    }
+
+    fn example4<'a, S: DateStyler>(m: Month, y: i32, es: S) -> Monthly<'a, S> {
+        let header_style = Style::default()
+            .add_modifier(Modifier::BOLD)
+            .fg(Color::Green);
+
+        let default_style = Style::default()
+            .add_modifier(Modifier::BOLD)
+            .bg(Color::Rgb(50, 50, 50));
+
+        Monthly::new(Date::from_calendar_date(y, m, 1).unwrap(), es)
+            .show_weekdays_header(header_style)
+            .default_style(default_style)
+    }
+
+    fn example5<'a, S: DateStyler>(m: Month, y: i32, es: S) -> Monthly<'a, S> {
+        let header_style = Style::default()
+            .add_modifier(Modifier::BOLD)
+            .fg(Color::Green);
+
+        let default_style = Style::default()
+            .add_modifier(Modifier::BOLD)
+            .bg(Color::Rgb(50, 50, 50));
+
+        Monthly::new(Date::from_calendar_date(y, m, 1).unwrap(), es)
+            .show_month_header(header_style)
+            .default_style(default_style)
+    }
+}
--- a/examples/calendar.tape
+++ b/examples/calendar.tape
@@ -0,0 +1,12 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/calendar.tape`
+Output "target/calendar.gif"
+Set Theme "Aardvark Blue"
+Set Width 1200
+Set Height 800
+Hide
+Type "cargo run --example=calendar --features=crossterm,widget-calendar"
+Enter
+Sleep 3s
+Show
+Sleep 5s
--- a/examples/canvas.rs
+++ b/examples/canvas.rs
@@ -1,204 +1,198 @@
-extern crate termion;
-extern crate tui;
+use std::{
+    io::{self, stdout, Stdout},
+    time::{Duration, Instant},
+};

-use std::io;
-use std::sync::mpsc;
-use std::thread;
-use std::time;
+use crossterm::{
+    event::{self, Event, KeyCode},
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    ExecutableCommand,
+};
+use ratatui::{
+    prelude::*,
+    widgets::{canvas::*, *},
+};

-use termion::event;
-use termion::input::TermRead;
-
-use tui::backend::MouseBackend;
-use tui::layout::{Constraint, Direction, Layout, Rect};
-use tui::style::Color;
-use tui::widgets::canvas::{Canvas, Line, Map, MapResolution};
-use tui::widgets::{Block, Borders, Widget};
-use tui::Terminal;
+fn main() -> io::Result<()> {
+    App::run()
+}

 struct App {
-    size: Rect,
    x: f64,
    y: f64,
-    ball: Rect,
+    ball: Circle,
    playground: Rect,
-    vx: u16,
-    vy: u16,
-    dir_x: bool,
-    dir_y: bool,
+    vx: f64,
+    vy: f64,
+    tick_count: u64,
+    marker: Marker,
 }

 impl App {
    fn new() -> App {
        App {
-            size: Default::default(),
            x: 0.0,
            y: 0.0,
-            ball: Rect::new(10, 30, 10, 10),
-            playground: Rect::new(10, 10, 100, 100),
-            vx: 1,
-            vy: 1,
-            dir_x: true,
-            dir_y: true,
-        }
-    }
-
-    fn advance(&mut self) {
-        if self.ball.left() < self.playground.left() || self.ball.right() > self.playground.right()
-        {
-            self.dir_x = !self.dir_x;
-        }
-        if self.ball.top() < self.playground.top() || self.ball.bottom() > self.playground.bottom()
-        {
-            self.dir_y = !self.dir_y;
-        }
-
-        if self.dir_x {
-            self.ball.x += self.vx;
-        } else {
-            self.ball.x -= self.vx;
-        }
-
-        if self.dir_y {
-            self.ball.y += self.vy;
-        } else {
-            self.ball.y -= self.vy
-        }
-    }
-}
-
-enum Event {
-    Input(event::Key),
-    Tick,
-}
-
-fn main() {
-    // Terminal initialization
-    let backend = MouseBackend::new().unwrap();
-    let mut terminal = Terminal::new(backend).unwrap();
-
-    // Channels
-    let (tx, rx) = mpsc::channel();
-    let input_tx = tx.clone();
-    let clock_tx = tx.clone();
-
-    // Input
-    thread::spawn(move || {
-        let stdin = io::stdin();
-        for c in stdin.keys() {
-            let evt = c.unwrap();
-            input_tx.send(Event::Input(evt)).unwrap();
-            if evt == event::Key::Char('q') {
-                break;
-            }
-        }
-    });
-
-    // Tick
-    thread::spawn(move || loop {
-        clock_tx.send(Event::Tick).unwrap();
-        thread::sleep(time::Duration::from_millis(500));
-    });
-
-    // App
-    let mut app = App::new();
-
-    // First draw call
-    terminal.clear().unwrap();
-    terminal.hide_cursor().unwrap();
-    app.size = terminal.size().unwrap();
-    draw(&mut terminal, &app).unwrap();
-
-    loop {
-        let size = terminal.size().unwrap();
-        if size != app.size {
-            terminal.resize(size).unwrap();
-            app.size = size;
-        }
-
-        let evt = rx.recv().unwrap();
-        match evt {
-            Event::Input(input) => match input {
-                event::Key::Char('q') => {
-                    break;
-                }
-                event::Key::Down => {
-                    app.y += 1.0;
-                }
-                event::Key::Up => {
-                    app.y -= 1.0;
-                }
-                event::Key::Right => {
-                    app.x += 1.0;
-                }
-                event::Key::Left => {
-                    app.x -= 1.0;
-                }
-
-                _ => {}
+            ball: Circle {
+                x: 20.0,
+                y: 40.0,
+                radius: 10.0,
+                color: Color::Yellow,
            },
-            Event::Tick => {
-                app.advance();
-            }
+            playground: Rect::new(10, 10, 200, 100),
+            vx: 1.0,
+            vy: 1.0,
+            tick_count: 0,
+            marker: Marker::Dot,
        }
-        draw(&mut terminal, &app).unwrap();
    }

-    terminal.show_cursor().unwrap();
-}
+    pub fn run() -> io::Result<()> {
+        let mut terminal = init_terminal()?;
+        let mut app = App::new();
+        let mut last_tick = Instant::now();
+        let tick_rate = Duration::from_millis(16);
+        loop {
+            let _ = terminal.draw(|frame| app.ui(frame));
+            let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+            if event::poll(timeout)? {
+                if let Event::Key(key) = event::read()? {
+                    match key.code {
+                        KeyCode::Char('q') => break,
+                        KeyCode::Down => app.y += 1.0,
+                        KeyCode::Up => app.y -= 1.0,
+                        KeyCode::Right => app.x += 1.0,
+                        KeyCode::Left => app.x -= 1.0,
+                        _ => {}
+                    }
+                }
+            }

-fn draw(t: &mut Terminal<MouseBackend>, app: &App) -> Result<(), io::Error> {
-    t.draw(|mut f| {
-        let chunks = Layout::default()
+            if last_tick.elapsed() >= tick_rate {
+                app.on_tick();
+                last_tick = Instant::now();
+            }
+        }
+        restore_terminal()
+    }
+
+    fn on_tick(&mut self) {
+        self.tick_count += 1;
+        // only change marker every 180 ticks (3s) to avoid stroboscopic effect
+        if (self.tick_count % 180) == 0 {
+            self.marker = match self.marker {
+                Marker::Dot => Marker::Braille,
+                Marker::Braille => Marker::Block,
+                Marker::Block => Marker::HalfBlock,
+                Marker::HalfBlock => Marker::Bar,
+                Marker::Bar => Marker::Dot,
+            };
+        }
+        // bounce the ball by flipping the velocity vector
+        let ball = &self.ball;
+        let playground = self.playground;
+        if ball.x - ball.radius < playground.left() as f64
+            || ball.x + ball.radius > playground.right() as f64
+        {
+            self.vx = -self.vx;
+        }
+        if ball.y - ball.radius < playground.top() as f64
+            || ball.y + ball.radius > playground.bottom() as f64
+        {
+            self.vy = -self.vy;
+        }
+
+        self.ball.x += self.vx;
+        self.ball.y += self.vy;
+    }
+
+    fn ui(&self, frame: &mut Frame) {
+        let main_layout = Layout::default()
            .direction(Direction::Horizontal)
-            .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-            .split(app.size);
+            .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
+            .split(frame.size());
+
+        let right_layout = Layout::default()
+            .direction(Direction::Vertical)
+            .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
+            .split(main_layout[1]);
+
+        frame.render_widget(self.map_canvas(), main_layout[0]);
+        frame.render_widget(self.pong_canvas(), right_layout[0]);
+        frame.render_widget(self.boxes_canvas(right_layout[1]), right_layout[1]);
+    }
+
+    fn map_canvas(&self) -> impl Widget + '_ {
        Canvas::default()
            .block(Block::default().borders(Borders::ALL).title("World"))
+            .marker(self.marker)
            .paint(|ctx| {
                ctx.draw(&Map {
-                    color: Color::White,
+                    color: Color::Green,
                    resolution: MapResolution::High,
                });
-                ctx.print(app.x, -app.y, "You are here", Color::Yellow);
+                ctx.print(self.x, -self.y, "You are here".yellow());
            })
            .x_bounds([-180.0, 180.0])
            .y_bounds([-90.0, 90.0])
-            .render(&mut f, chunks[0]);
+    }
+
+    fn pong_canvas(&self) -> impl Widget + '_ {
        Canvas::default()
-            .block(Block::default().borders(Borders::ALL).title("List"))
+            .block(Block::default().borders(Borders::ALL).title("Pong"))
+            .marker(self.marker)
            .paint(|ctx| {
-                ctx.draw(&Line {
-                    x1: f64::from(app.ball.left()),
-                    y1: f64::from(app.ball.top()),
-                    x2: f64::from(app.ball.right()),
-                    y2: f64::from(app.ball.top()),
-                    color: Color::Yellow,
-                });
-                ctx.draw(&Line {
-                    x1: f64::from(app.ball.right()),
-                    y1: f64::from(app.ball.top()),
-                    x2: f64::from(app.ball.right()),
-                    y2: f64::from(app.ball.bottom()),
-                    color: Color::Yellow,
-                });
-                ctx.draw(&Line {
-                    x1: f64::from(app.ball.right()),
-                    y1: f64::from(app.ball.bottom()),
-                    x2: f64::from(app.ball.left()),
-                    y2: f64::from(app.ball.bottom()),
-                    color: Color::Yellow,
-                });
-                ctx.draw(&Line {
-                    x1: f64::from(app.ball.left()),
-                    y1: f64::from(app.ball.bottom()),
-                    x2: f64::from(app.ball.left()),
-                    y2: f64::from(app.ball.top()),
-                    color: Color::Yellow,
-                });
+                ctx.draw(&self.ball);
            })
-            .x_bounds([10.0, 110.0])
+            .x_bounds([10.0, 210.0])
            .y_bounds([10.0, 110.0])
-            .render(&mut f, chunks[1]);
-    })
+    }
+
+    fn boxes_canvas(&self, area: Rect) -> impl Widget {
+        let (left, right, bottom, top) =
+            (0.0, area.width as f64, 0.0, area.height as f64 * 2.0 - 4.0);
+        Canvas::default()
+            .block(Block::default().borders(Borders::ALL).title("Rects"))
+            .marker(self.marker)
+            .x_bounds([left, right])
+            .y_bounds([bottom, top])
+            .paint(|ctx| {
+                for i in 0..=11 {
+                    ctx.draw(&Rectangle {
+                        x: (i * i + 3 * i) as f64 / 2.0 + 2.0,
+                        y: 2.0,
+                        width: i as f64,
+                        height: i as f64,
+                        color: Color::Red,
+                    });
+                    ctx.draw(&Rectangle {
+                        x: (i * i + 3 * i) as f64 / 2.0 + 2.0,
+                        y: 21.0,
+                        width: i as f64,
+                        height: i as f64,
+                        color: Color::Blue,
+                    });
+                }
+                for i in 0..100 {
+                    if i % 10 != 0 {
+                        ctx.print(i as f64 + 1.0, 0.0, format!("{i}", i = i % 10));
+                    }
+                    if i % 2 == 0 && i % 10 != 0 {
+                        ctx.print(0.0, i as f64, format!("{i}", i = i % 10));
+                    }
+                }
+            })
+    }
+}
+
+fn init_terminal() -> io::Result<Terminal<CrosstermBackend<Stdout>>> {
+    enable_raw_mode()?;
+    stdout().execute(EnterAlternateScreen)?;
+    Terminal::new(CrosstermBackend::new(stdout()))
+}
+
+fn restore_terminal() -> io::Result<()> {
+    disable_raw_mode()?;
+    stdout().execute(LeaveAlternateScreen)?;
+    Ok(())
 }
--- a/examples/canvas.tape
+++ b/examples/canvas.tape
@@ -0,0 +1,13 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/canvas.tape`
+Output "target/canvas.gif"
+Set Theme "Aardvark Blue"
+Set FontSize 12
+Set Width 1200
+Set Height 800
+Hide
+Type "cargo run --example=canvas --features=crossterm"
+Enter
+Sleep 2s
+Show
+Sleep 30s
--- a/examples/chart.rs
+++ b/examples/chart.rs
@@ -1,25 +1,56 @@
-extern crate termion;
-extern crate tui;
+use std::{
+    error::Error,
+    io,
+    time::{Duration, Instant},
+};

-mod util;
-use util::*;
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{prelude::*, widgets::*};

-use std::io;
-use std::sync::mpsc;
-use std::thread;
-use std::time;
+const DATA: [(f64, f64); 5] = [(0.0, 0.0), (1.0, 1.0), (2.0, 2.0), (3.0, 3.0), (4.0, 4.0)];
+const DATA2: [(f64, f64); 7] = [
+    (0.0, 0.0),
+    (10.0, 1.0),
+    (20.0, 0.5),
+    (30.0, 1.5),
+    (40.0, 1.0),
+    (50.0, 2.5),
+    (60.0, 3.0),
+];

-use termion::event;
-use termion::input::TermRead;
+#[derive(Clone)]
+pub struct SinSignal {
+    x: f64,
+    interval: f64,
+    period: f64,
+    scale: f64,
+}

-use tui::backend::MouseBackend;
-use tui::layout::Rect;
-use tui::style::{Color, Modifier, Style};
-use tui::widgets::{Axis, Block, Borders, Chart, Dataset, Marker, Widget};
-use tui::Terminal;
+impl SinSignal {
+    pub fn new(interval: f64, period: f64, scale: f64) -> SinSignal {
+        SinSignal {
+            x: 0.0,
+            interval,
+            period,
+            scale,
+        }
+    }
+}
+
+impl Iterator for SinSignal {
+    type Item = (f64, f64);
+    fn next(&mut self) -> Option<Self::Item> {
+        let point = (self.x, (self.x * 1.0 / self.period).sin() * self.scale);
+        self.x += self.interval;
+        Some(point)
+    }
+}

 struct App {
-    size: Rect,
    signal1: SinSignal,
    data1: Vec<(f64, f64)>,
    signal2: SinSignal,
@@ -34,7 +65,6 @@ impl App {
        let data1 = signal1.by_ref().take(200).collect::<Vec<(f64, f64)>>();
        let data2 = signal2.by_ref().take(200).collect::<Vec<(f64, f64)>>();
        App {
-            size: Rect::default(),
            signal1,
            data1,
            signal2,
@@ -43,7 +73,7 @@ impl App {
        }
    }

-    fn advance(&mut self) {
+    fn on_tick(&mut self) {
        for _ in 0..5 {
            self.data1.remove(0);
        }
@@ -57,111 +87,168 @@ impl App {
    }
 }

-enum Event {
-    Input(event::Key),
-    Tick,
-}
+fn main() -> Result<(), Box<dyn Error>> {
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;

-fn main() {
-    // Terminal initialization
-    let backend = MouseBackend::new().unwrap();
-    let mut terminal = Terminal::new(backend).unwrap();
+    // create app and run it
+    let tick_rate = Duration::from_millis(250);
+    let app = App::new();
+    let res = run_app(&mut terminal, app, tick_rate);

-    // Channels
-    let (tx, rx) = mpsc::channel();
-    let input_tx = tx.clone();
-    let clock_tx = tx.clone();
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;

-    // Input
-    thread::spawn(move || {
-        let stdin = io::stdin();
-        for c in stdin.keys() {
-            let evt = c.unwrap();
-            input_tx.send(Event::Input(evt)).unwrap();
-            if evt == event::Key::Char('q') {
-                break;
-            }
-        }
-    });
-
-    // Tick
-    thread::spawn(move || loop {
-        clock_tx.send(Event::Tick).unwrap();
-        thread::sleep(time::Duration::from_millis(500));
-    });
-
-    // App
-    let mut app = App::new();
-
-    // First draw call
-    terminal.clear().unwrap();
-    terminal.hide_cursor().unwrap();
-    app.size = terminal.size().unwrap();
-    draw(&mut terminal, &app).unwrap();
-
-    loop {
-        let size = terminal.size().unwrap();
-        if app.size != size {
-            terminal.resize(size).unwrap();
-            app.size = size;
-        }
-
-        let evt = rx.recv().unwrap();
-        match evt {
-            Event::Input(input) => if input == event::Key::Char('q') {
-                break;
-            },
-            Event::Tick => {
-                app.advance();
-            }
-        }
-        draw(&mut terminal, &app).unwrap();
+    if let Err(err) = res {
+        println!("{err:?}");
    }

-    terminal.show_cursor().unwrap();
+    Ok(())
 }

-fn draw(t: &mut Terminal<MouseBackend>, app: &App) -> Result<(), io::Error> {
-    t.draw(|mut f| {
-        Chart::default()
-            .block(
-                Block::default()
-                    .title("Chart")
-                    .title_style(Style::default().fg(Color::Cyan).modifier(Modifier::Bold))
-                    .borders(Borders::ALL),
-            )
-            .x_axis(
-                Axis::default()
-                    .title("X Axis")
-                    .style(Style::default().fg(Color::Gray))
-                    .labels_style(Style::default().modifier(Modifier::Italic))
-                    .bounds(app.window)
-                    .labels(&[
-                        &format!("{}", app.window[0]),
-                        &format!("{}", (app.window[0] + app.window[1]) / 2.0),
-                        &format!("{}", app.window[1]),
-                    ]),
-            )
-            .y_axis(
-                Axis::default()
-                    .title("Y Axis")
-                    .style(Style::default().fg(Color::Gray))
-                    .labels_style(Style::default().modifier(Modifier::Italic))
-                    .bounds([-20.0, 20.0])
-                    .labels(&["-20", "0", "20"]),
-            )
-            .datasets(&[
-                Dataset::default()
-                    .name("data2")
-                    .marker(Marker::Dot)
-                    .style(Style::default().fg(Color::Cyan))
-                    .data(&app.data1),
-                Dataset::default()
-                    .name("data3")
-                    .marker(Marker::Braille)
-                    .style(Style::default().fg(Color::Yellow))
-                    .data(&app.data2),
-            ])
-            .render(&mut f, app.size);
-    })
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    mut app: App,
+    tick_rate: Duration,
+) -> io::Result<()> {
+    let mut last_tick = Instant::now();
+    loop {
+        terminal.draw(|f| ui(f, &app))?;
+
+        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+        if crossterm::event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                if let KeyCode::Char('q') = key.code {
+                    return Ok(());
+                }
+            }
+        }
+        if last_tick.elapsed() >= tick_rate {
+            app.on_tick();
+            last_tick = Instant::now();
+        }
+    }
+}
+
+fn ui(f: &mut Frame, app: &App) {
+    let size = f.size();
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Ratio(1, 3),
+            Constraint::Ratio(1, 3),
+            Constraint::Ratio(1, 3),
+        ])
+        .split(size);
+    let x_labels = vec![
+        Span::styled(
+            format!("{}", app.window[0]),
+            Style::default().add_modifier(Modifier::BOLD),
+        ),
+        Span::raw(format!("{}", (app.window[0] + app.window[1]) / 2.0)),
+        Span::styled(
+            format!("{}", app.window[1]),
+            Style::default().add_modifier(Modifier::BOLD),
+        ),
+    ];
+    let datasets = vec![
+        Dataset::default()
+            .name("data2")
+            .marker(symbols::Marker::Dot)
+            .style(Style::default().fg(Color::Cyan))
+            .data(&app.data1),
+        Dataset::default()
+            .name("data3")
+            .marker(symbols::Marker::Braille)
+            .style(Style::default().fg(Color::Yellow))
+            .data(&app.data2),
+    ];
+
+    let chart = Chart::new(datasets)
+        .block(
+            Block::default()
+                .title("Chart 1".cyan().bold())
+                .borders(Borders::ALL),
+        )
+        .x_axis(
+            Axis::default()
+                .title("X Axis")
+                .style(Style::default().fg(Color::Gray))
+                .labels(x_labels)
+                .bounds(app.window),
+        )
+        .y_axis(
+            Axis::default()
+                .title("Y Axis")
+                .style(Style::default().fg(Color::Gray))
+                .labels(vec!["-20".bold(), "0".into(), "20".bold()])
+                .bounds([-20.0, 20.0]),
+        );
+    f.render_widget(chart, chunks[0]);
+
+    let datasets = vec![Dataset::default()
+        .name("data")
+        .marker(symbols::Marker::Braille)
+        .style(Style::default().fg(Color::Yellow))
+        .graph_type(GraphType::Line)
+        .data(&DATA)];
+    let chart = Chart::new(datasets)
+        .block(
+            Block::default()
+                .title("Chart 2".cyan().bold())
+                .borders(Borders::ALL),
+        )
+        .x_axis(
+            Axis::default()
+                .title("X Axis")
+                .style(Style::default().fg(Color::Gray))
+                .bounds([0.0, 5.0])
+                .labels(vec!["0".bold(), "2.5".into(), "5.0".bold()]),
+        )
+        .y_axis(
+            Axis::default()
+                .title("Y Axis")
+                .style(Style::default().fg(Color::Gray))
+                .bounds([0.0, 5.0])
+                .labels(vec!["0".bold(), "2.5".into(), "5.0".bold()]),
+        );
+    f.render_widget(chart, chunks[1]);
+
+    let datasets = vec![Dataset::default()
+        .name("data")
+        .marker(symbols::Marker::Braille)
+        .style(Style::default().fg(Color::Yellow))
+        .graph_type(GraphType::Line)
+        .data(&DATA2)];
+    let chart = Chart::new(datasets)
+        .block(
+            Block::default()
+                .title("Chart 3".cyan().bold())
+                .borders(Borders::ALL),
+        )
+        .x_axis(
+            Axis::default()
+                .title("X Axis")
+                .style(Style::default().fg(Color::Gray))
+                .bounds([0.0, 50.0])
+                .labels(vec!["0".bold(), "25".into(), "50".bold()]),
+        )
+        .y_axis(
+            Axis::default()
+                .title("Y Axis")
+                .style(Style::default().fg(Color::Gray))
+                .bounds([0.0, 5.0])
+                .labels(vec!["0".bold(), "2.5".into(), "5".bold()]),
+        );
+    f.render_widget(chart, chunks[2]);
 }
--- a/examples/chart.tape
+++ b/examples/chart.tape
@@ -0,0 +1,12 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/chart.tape`
+Output "target/chart.gif"
+Set Theme "Aardvark Blue"
+Set Width 1200
+Set Height 800
+Hide
+Type "cargo run --example=chart --features=crossterm"
+Enter
+Sleep 1s
+Show
+Sleep 5s
--- a/examples/colors.rs
+++ b/examples/colors.rs
@@ -0,0 +1,295 @@
+/// This example shows all the colors supported by ratatui. It will render a grid of foreground
+/// and background colors with their names and indexes.
+use std::{
+    error::Error,
+    io::{self, Stdout},
+    result,
+    time::Duration,
+};
+
+use crossterm::{
+    event::{self, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use itertools::Itertools;
+use ratatui::{prelude::*, widgets::*};
+
+type Result<T> = result::Result<T, Box<dyn Error>>;
+
+fn main() -> Result<()> {
+    let mut terminal = setup_terminal()?;
+    let res = run_app(&mut terminal);
+    restore_terminal(terminal)?;
+    if let Err(err) = res {
+        eprintln!("{err:?}");
+    }
+    Ok(())
+}
+
+fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
+    loop {
+        terminal.draw(ui)?;
+
+        if event::poll(Duration::from_millis(250))? {
+            if let Event::Key(key) = event::read()? {
+                if let KeyCode::Char('q') = key.code {
+                    return Ok(());
+                }
+            }
+        }
+    }
+}
+
+fn ui(frame: &mut Frame) {
+    let layout = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(30),
+            Constraint::Length(17),
+            Constraint::Length(2),
+        ])
+        .split(frame.size());
+
+    render_named_colors(frame, layout[0]);
+    render_indexed_colors(frame, layout[1]);
+    render_indexed_grayscale(frame, layout[2]);
+}
+
+const NAMED_COLORS: [Color; 16] = [
+    Color::Black,
+    Color::Red,
+    Color::Green,
+    Color::Yellow,
+    Color::Blue,
+    Color::Magenta,
+    Color::Cyan,
+    Color::Gray,
+    Color::DarkGray,
+    Color::LightRed,
+    Color::LightGreen,
+    Color::LightYellow,
+    Color::LightBlue,
+    Color::LightMagenta,
+    Color::LightCyan,
+    Color::White,
+];
+
+fn render_named_colors(frame: &mut Frame, area: Rect) {
+    let layout = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Length(3); 10])
+        .split(area);
+
+    render_fg_named_colors(frame, Color::Reset, layout[0]);
+    render_fg_named_colors(frame, Color::Black, layout[1]);
+    render_fg_named_colors(frame, Color::DarkGray, layout[2]);
+    render_fg_named_colors(frame, Color::Gray, layout[3]);
+    render_fg_named_colors(frame, Color::White, layout[4]);
+
+    render_bg_named_colors(frame, Color::Reset, layout[5]);
+    render_bg_named_colors(frame, Color::Black, layout[6]);
+    render_bg_named_colors(frame, Color::DarkGray, layout[7]);
+    render_bg_named_colors(frame, Color::Gray, layout[8]);
+    render_bg_named_colors(frame, Color::White, layout[9]);
+}
+
+fn render_fg_named_colors(frame: &mut Frame, bg: Color, area: Rect) {
+    let block = title_block(format!("Foreground colors on {bg} background"));
+    let inner = block.inner(area);
+    frame.render_widget(block, area);
+
+    let layout = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Length(1); 2])
+        .split(inner)
+        .iter()
+        .flat_map(|area| {
+            Layout::default()
+                .direction(Direction::Horizontal)
+                .constraints([Constraint::Ratio(1, 8); 8])
+                .split(*area)
+                .to_vec()
+        })
+        .collect_vec();
+    for (i, &fg) in NAMED_COLORS.iter().enumerate() {
+        let color_name = fg.to_string();
+        let paragraph = Paragraph::new(color_name).fg(fg).bg(bg);
+        frame.render_widget(paragraph, layout[i]);
+    }
+}
+
+fn render_bg_named_colors(frame: &mut Frame, fg: Color, area: Rect) {
+    let block = title_block(format!("Background colors with {fg} foreground"));
+    let inner = block.inner(area);
+    frame.render_widget(block, area);
+
+    let layout = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Length(1); 2])
+        .split(inner)
+        .iter()
+        .flat_map(|area| {
+            Layout::default()
+                .direction(Direction::Horizontal)
+                .constraints([Constraint::Ratio(1, 8); 8])
+                .split(*area)
+                .to_vec()
+        })
+        .collect_vec();
+    for (i, &bg) in NAMED_COLORS.iter().enumerate() {
+        let color_name = bg.to_string();
+        let paragraph = Paragraph::new(color_name).fg(fg).bg(bg);
+        frame.render_widget(paragraph, layout[i]);
+    }
+}
+
+fn render_indexed_colors(frame: &mut Frame, area: Rect) {
+    let block = title_block("Indexed colors".into());
+    let inner = block.inner(area);
+    frame.render_widget(block, area);
+
+    let layout = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(1), // 0 - 15
+            Constraint::Length(1), // blank
+            Constraint::Min(6),    // 16 - 123
+            Constraint::Length(1), // blank
+            Constraint::Min(6),    // 124 - 231
+            Constraint::Length(1), // blank
+        ])
+        .split(inner);
+
+    //    0   1   2   3   4   5    6   7   8   9  10  11   12  13  14  15
+    let color_layout = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Length(5); 16])
+        .split(layout[0]);
+    for i in 0..16 {
+        let color = Color::Indexed(i);
+        let color_index = format!("{i:0>2}");
+        let bg = if i < 1 { Color::DarkGray } else { Color::Black };
+        let paragraph = Paragraph::new(Line::from(vec![
+            color_index.fg(color).bg(bg),
+            "██".bg(color).fg(color),
+        ]));
+        frame.render_widget(paragraph, color_layout[i as usize]);
+    }
+
+    //   16  17  18  19  20  21   52  53  54  55  56  57   88  89  90  91  92  93
+    //   22  23  24  25  26  27   58  59  60  61  62  63   94  95  96  97  98  99
+    //   28  29  30  31  32  33   64  65  66  67  68  69  100 101 102 103 104 105
+    //   34  35  36  37  38  39   70  71  72  73  74  75  106 107 108 109 110 111
+    //   40  41  42  43  44  45   76  77  78  79  80  81  112 113 114 115 116 117
+    //   46  47  48  49  50  51   82  83  84  85  86  87  118 119 120 121 122 123
+    //
+    //  124 125 126 127 128 129  160 161 162 163 164 165  196 197 198 199 200 201
+    //  130 131 132 133 134 135  166 167 168 169 170 171  202 203 204 205 206 207
+    //  136 137 138 139 140 141  172 173 174 175 176 177  208 209 210 211 212 213
+    //  142 143 144 145 146 147  178 179 180 181 182 183  214 215 216 217 218 219
+    //  148 149 150 151 152 153  184 185 186 187 188 189  220 221 222 223 224 225
+    //  154 155 156 157 158 159  190 191 192 193 194 195  226 227 228 229 230 231
+
+    // the above looks complex but it's so the colors are grouped into blocks that display nicely
+    let index_layout = [layout[2], layout[4]]
+        .iter()
+        // two rows of 3 columns
+        .flat_map(|area| {
+            Layout::default()
+                .direction(Direction::Horizontal)
+                .constraints([Constraint::Length(27); 3])
+                .split(*area)
+                .to_vec()
+        })
+        // each with 6 rows
+        .flat_map(|area| {
+            Layout::default()
+                .direction(Direction::Vertical)
+                .constraints([Constraint::Length(1); 6])
+                .split(area)
+                .to_vec()
+        })
+        // each with 6 columns
+        .flat_map(|area| {
+            Layout::default()
+                .direction(Direction::Horizontal)
+                .constraints([Constraint::Min(4); 6])
+                .split(area)
+                .to_vec()
+        })
+        .collect_vec();
+
+    for i in 16..=231 {
+        let color = Color::Indexed(i);
+        let color_index = format!("{i:0>3}");
+        let paragraph = Paragraph::new(Line::from(vec![
+            color_index.fg(color).bg(Color::Reset),
+            ".".bg(color).fg(color),
+            // There's a bug in VHS that seems to bleed backgrounds into the next
+            // character. This is a workaround to make the bug less obvious.
+            "███".reversed(),
+        ]));
+        frame.render_widget(paragraph, index_layout[i as usize - 16]);
+    }
+}
+
+fn title_block(title: String) -> Block<'static> {
+    Block::default()
+        .borders(Borders::TOP)
+        .border_style(Style::new().dark_gray())
+        .title(title)
+        .title_alignment(Alignment::Center)
+        .title_style(Style::new().reset())
+}
+
+fn render_indexed_grayscale(frame: &mut Frame, area: Rect) {
+    let layout = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(1), // 232 - 243
+            Constraint::Length(1), // 244 - 255
+        ])
+        .split(area)
+        .iter()
+        .flat_map(|area| {
+            Layout::default()
+                .direction(Direction::Horizontal)
+                .constraints([Constraint::Length(6); 12])
+                .split(*area)
+                .to_vec()
+        })
+        .collect_vec();
+
+    for i in 232..=255 {
+        let color = Color::Indexed(i);
+        let color_index = format!("{i:0>3}");
+        // make the dark colors easier to read
+        let bg = if i < 244 { Color::Gray } else { Color::Black };
+        let paragraph = Paragraph::new(Line::from(vec![
+            color_index.fg(color).bg(bg),
+            "██".bg(color).fg(color),
+            // There's a bug in VHS that seems to bleed backgrounds into the next
+            // character. This is a workaround to make the bug less obvious.
+            "███████".reversed(),
+        ]));
+        frame.render_widget(paragraph, layout[i as usize - 232]);
+    }
+}
+
+fn setup_terminal() -> Result<Terminal<CrosstermBackend<Stdout>>> {
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+    terminal.hide_cursor()?;
+    Ok(terminal)
+}
+
+fn restore_terminal(mut terminal: Terminal<CrosstermBackend<Stdout>>) -> Result<()> {
+    disable_raw_mode()?;
+    execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
+    terminal.show_cursor()?;
+    Ok(())
+}
--- a/examples/colors.tape
+++ b/examples/colors.tape
@@ -0,0 +1,12 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/colors.tape`
+Output "target/colors.gif"
+Set Theme "Aardvark Blue"
+Set Width 1200
+Set Height 1410
+Hide
+Type "cargo run --example=colors --features=crossterm"
+Enter
+Sleep 2s
+Show
+Sleep 1s
--- a/examples/colors_rgb.rs
+++ b/examples/colors_rgb.rs
@@ -0,0 +1,147 @@
+/// This example shows the full range of RGB colors that can be displayed in the terminal.
+///
+/// Requires a terminal that supports 24-bit color (true color) and unicode.
+use std::{
+    error::Error,
+    io::{stdout, Stdout},
+    rc::Rc,
+    time::Duration,
+};
+
+use crossterm::{
+    event::{self, Event, KeyCode, KeyEventKind},
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    ExecutableCommand,
+};
+use palette::{
+    convert::{FromColorUnclamped, IntoColorUnclamped},
+    Okhsv, Srgb,
+};
+use ratatui::{prelude::*, widgets::*};
+
+type Result<T> = std::result::Result<T, Box<dyn Error>>;
+
+fn main() -> Result<()> {
+    install_panic_hook();
+    App::new()?.run()
+}
+
+struct App {
+    terminal: Terminal<CrosstermBackend<Stdout>>,
+    should_quit: bool,
+}
+
+impl App {
+    pub fn new() -> Result<Self> {
+        Ok(Self {
+            terminal: Terminal::new(CrosstermBackend::new(stdout()))?,
+            should_quit: false,
+        })
+    }
+
+    pub fn run(mut self) -> Result<()> {
+        init_terminal()?;
+        self.terminal.clear()?;
+        while !self.should_quit {
+            self.draw()?;
+            self.handle_events()?;
+        }
+        restore_terminal()?;
+        Ok(())
+    }
+
+    fn draw(&mut self) -> Result<()> {
+        self.terminal.draw(|frame| {
+            frame.render_widget(RgbColors, frame.size());
+        })?;
+        Ok(())
+    }
+
+    fn handle_events(&mut self) -> Result<()> {
+        if event::poll(Duration::from_millis(100))? {
+            if let Event::Key(key) = event::read()? {
+                if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                    self.should_quit = true;
+                };
+            }
+        }
+        Ok(())
+    }
+}
+
+impl Drop for App {
+    fn drop(&mut self) {
+        let _ = restore_terminal();
+    }
+}
+
+struct RgbColors;
+
+impl Widget for RgbColors {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let layout = Self::layout(area);
+        Self::render_title(layout[0], buf);
+        Self::render_colors(layout[1], buf);
+    }
+}
+
+impl RgbColors {
+    fn layout(area: Rect) -> Rc<[Rect]> {
+        Layout::default()
+            .direction(Direction::Vertical)
+            .constraints([Constraint::Length(1), Constraint::Min(0)])
+            .split(area)
+    }
+
+    fn render_title(area: Rect, buf: &mut Buffer) {
+        Paragraph::new("colors_rgb example. Press q to quit")
+            .dark_gray()
+            .alignment(Alignment::Center)
+            .render(area, buf);
+    }
+
+    /// Render a colored grid of half block characters (`"▀"`) each with a different RGB color.
+    fn render_colors(area: Rect, buf: &mut Buffer) {
+        for (xi, x) in (area.left()..area.right()).enumerate() {
+            for (yi, y) in (area.top()..area.bottom()).enumerate() {
+                let hue = xi as f32 * 360.0 / area.width as f32;
+
+                let value_fg = (yi as f32) / (area.height as f32 - 0.5);
+                let fg = Okhsv::<f32>::new(hue, Okhsv::max_saturation(), value_fg);
+                let fg: Srgb = fg.into_color_unclamped();
+                let fg: Srgb<u8> = fg.into_format();
+                let fg = Color::Rgb(fg.red, fg.green, fg.blue);
+
+                let value_bg = (yi as f32 + 0.5) / (area.height as f32 - 0.5);
+                let bg = Okhsv::new(hue, Okhsv::max_saturation(), value_bg);
+                let bg = Srgb::<f32>::from_color_unclamped(bg);
+                let bg: Srgb<u8> = bg.into_format();
+                let bg = Color::Rgb(bg.red, bg.green, bg.blue);
+
+                buf.get_mut(x, y).set_char('▀').set_fg(fg).set_bg(bg);
+            }
+        }
+    }
+}
+
+/// Install a panic hook that restores the terminal before panicking.
+fn install_panic_hook() {
+    better_panic::install();
+    let prev_hook = std::panic::take_hook();
+    std::panic::set_hook(Box::new(move |info| {
+        let _ = restore_terminal();
+        prev_hook(info);
+    }));
+}
+
+fn init_terminal() -> Result<()> {
+    enable_raw_mode()?;
+    stdout().execute(EnterAlternateScreen)?;
+    Ok(())
+}
+
+fn restore_terminal() -> Result<()> {
+    disable_raw_mode()?;
+    stdout().execute(LeaveAlternateScreen)?;
+    Ok(())
+}
--- a/examples/colors_rgb.tape
+++ b/examples/colors_rgb.tape
@@ -0,0 +1,13 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/colors_rgb.tape`
+Output "target/colors_rgb.gif"
+Set Theme "Aardvark Blue"
+Set Width 1200
+Set Height 800
+Hide
+Type "cargo run --example=colors_rgb --features=crossterm"
+Enter
+Sleep 2s
+Screenshot "target/colors_rgb.png"
+Show
+Sleep 1s
--- a/examples/crossterm.rs
+++ b/examples/crossterm.rs
@@ -1,50 +0,0 @@
-extern crate crossterm;
-extern crate tui;
-
-use std::error::Error;
-use std::io;
-
-use tui::backend::CrosstermBackend;
-use tui::layout::{Constraint, Direction, Layout};
-use tui::style::{Color, Modifier, Style};
-use tui::widgets::{Block, Borders, Paragraph, Text, Widget};
-use tui::Terminal;
-
-fn main() {
-    let mut terminal = Terminal::new(CrosstermBackend::new()).unwrap();
-    terminal.clear().unwrap();
-    terminal.hide_cursor().unwrap();
-    draw(&mut terminal).unwrap();
-    loop {
-        {
-            let input = crossterm::input(terminal.backend().screen());
-            match input.read_char() {
-                Ok(c) => if c == 'q' {
-                    break;
-                },
-                Err(e) => panic!("{}", e.description()),
-            };
-        }
-        draw(&mut terminal).unwrap();
-    }
-    terminal.show_cursor().unwrap();
-}
-
-fn draw(t: &mut Terminal<CrosstermBackend>) -> io::Result<()> {
-    let size = t.size()?;
-    t.draw(|mut f| {
-        let text = [
-            Text::Data("It "),
-            Text::StyledData("works", Style::default().fg(Color::Yellow)),
-        ];
-        Paragraph::new(text.iter())
-            .block(
-                Block::default()
-                    .title("Crossterm Backend")
-                    .title_style(Style::default().fg(Color::Yellow).modifier(Modifier::Bold))
-                    .borders(Borders::ALL)
-                    .border_style(Style::default().fg(Color::Magenta)),
-            )
-            .render(&mut f, size);
-    })
-}
--- a/examples/custom_widget.rs
+++ b/examples/custom_widget.rs
@@ -1,42 +1,272 @@
-extern crate tui;
+use std::{error::Error, io, ops::ControlFlow, time::Duration};

-use tui::backend::MouseBackend;
-use tui::buffer::Buffer;
-use tui::layout::Rect;
-use tui::style::Style;
-use tui::widgets::Widget;
-use tui::Terminal;
+use crossterm::{
+    event::{
+        self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, MouseButton, MouseEvent,
+        MouseEventKind,
+    },
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{prelude::*, widgets::*};

-struct Label<'a> {
-    text: &'a str,
+/// A custom widget that renders a button with a label, theme and state.
+#[derive(Debug, Clone)]
+struct Button<'a> {
+    label: Line<'a>,
+    theme: Theme,
+    state: State,
 }

-impl<'a> Default for Label<'a> {
-    fn default() -> Label<'a> {
-        Label { text: "" }
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum State {
+    Normal,
+    Selected,
+    Active,
+}
+
+#[derive(Debug, Clone, Copy)]
+struct Theme {
+    text: Color,
+    background: Color,
+    highlight: Color,
+    shadow: Color,
+}
+
+const BLUE: Theme = Theme {
+    text: Color::Rgb(16, 24, 48),
+    background: Color::Rgb(48, 72, 144),
+    highlight: Color::Rgb(64, 96, 192),
+    shadow: Color::Rgb(32, 48, 96),
+};
+
+const RED: Theme = Theme {
+    text: Color::Rgb(48, 16, 16),
+    background: Color::Rgb(144, 48, 48),
+    highlight: Color::Rgb(192, 64, 64),
+    shadow: Color::Rgb(96, 32, 32),
+};
+
+const GREEN: Theme = Theme {
+    text: Color::Rgb(16, 48, 16),
+    background: Color::Rgb(48, 144, 48),
+    highlight: Color::Rgb(64, 192, 64),
+    shadow: Color::Rgb(32, 96, 32),
+};
+
+/// A button with a label that can be themed.
+impl<'a> Button<'a> {
+    pub fn new<T: Into<Line<'a>>>(label: T) -> Button<'a> {
+        Button {
+            label: label.into(),
+            theme: BLUE,
+            state: State::Normal,
+        }
    }
-}

-impl<'a> Widget for Label<'a> {
-    fn draw(&mut self, area: Rect, buf: &mut Buffer) {
-        buf.set_string(area.left(), area.top(), self.text, &Style::default());
+    pub fn theme(mut self, theme: Theme) -> Button<'a> {
+        self.theme = theme;
+        self
    }
-}

-impl<'a> Label<'a> {
-    fn text(&mut self, text: &'a str) -> &mut Label<'a> {
-        self.text = text;
+    pub fn state(mut self, state: State) -> Button<'a> {
+        self.state = state;
        self
    }
 }

-fn main() {
-    let mut terminal = Terminal::new(MouseBackend::new().unwrap()).unwrap();
-    let size = terminal.size().unwrap();
-    terminal.clear().unwrap();
-    terminal
-        .draw(|mut f| {
-            Label::default().text("Test").render(&mut f, size);
-        })
-        .unwrap();
+impl<'a> Widget for Button<'a> {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let (background, text, shadow, highlight) = self.colors();
+        buf.set_style(area, Style::new().bg(background).fg(text));
+
+        // render top line if there's enough space
+        if area.height > 2 {
+            buf.set_string(
+                area.x,
+                area.y,
+                "▔".repeat(area.width as usize),
+                Style::new().fg(highlight).bg(background),
+            );
+        }
+        // render bottom line if there's enough space
+        if area.height > 1 {
+            buf.set_string(
+                area.x,
+                area.y + area.height - 1,
+                "▁".repeat(area.width as usize),
+                Style::new().fg(shadow).bg(background),
+            );
+        }
+        // render label centered
+        buf.set_line(
+            area.x + (area.width.saturating_sub(self.label.width() as u16)) / 2,
+            area.y + (area.height.saturating_sub(1)) / 2,
+            &self.label,
+            area.width,
+        );
+    }
+}
+
+impl Button<'_> {
+    fn colors(&self) -> (Color, Color, Color, Color) {
+        let theme = self.theme;
+        match self.state {
+            State::Normal => (theme.background, theme.text, theme.shadow, theme.highlight),
+            State::Selected => (theme.highlight, theme.text, theme.shadow, theme.highlight),
+            State::Active => (theme.background, theme.text, theme.highlight, theme.shadow),
+        }
+    }
+}
+
+fn main() -> Result<(), Box<dyn Error>> {
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+
+    // create app and run it
+    let res = run_app(&mut terminal);
+
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
+
+    if let Err(err) = res {
+        println!("{err:?}");
+    }
+
+    Ok(())
+}
+
+fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
+    let mut selected_button: usize = 0;
+    let button_states = &mut [State::Selected, State::Normal, State::Normal];
+    loop {
+        terminal.draw(|frame| ui(frame, button_states))?;
+        if !event::poll(Duration::from_millis(100))? {
+            continue;
+        }
+        match event::read()? {
+            Event::Key(key) => {
+                if key.kind != event::KeyEventKind::Press {
+                    continue;
+                }
+                if handle_key_event(key, button_states, &mut selected_button).is_break() {
+                    break;
+                }
+            }
+            Event::Mouse(mouse) => handle_mouse_event(mouse, button_states, &mut selected_button),
+            _ => (),
+        }
+    }
+    Ok(())
+}
+
+fn ui(frame: &mut Frame, states: &[State; 3]) {
+    let layout = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(1),
+            Constraint::Max(3),
+            Constraint::Length(1),
+            Constraint::Min(0), // ignore remaining space
+        ])
+        .split(frame.size());
+    frame.render_widget(
+        Paragraph::new("Custom Widget Example (mouse enabled)"),
+        layout[0],
+    );
+    render_buttons(frame, layout[1], states);
+    frame.render_widget(
+        Paragraph::new("←/→: select, Space: toggle, q: quit"),
+        layout[2],
+    );
+}
+
+fn render_buttons(frame: &mut Frame<'_>, area: Rect, states: &[State; 3]) {
+    let layout = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([
+            Constraint::Length(15),
+            Constraint::Length(15),
+            Constraint::Length(15),
+            Constraint::Min(0), // ignore remaining space
+        ])
+        .split(area);
+    frame.render_widget(Button::new("Red").theme(RED).state(states[0]), layout[0]);
+    frame.render_widget(
+        Button::new("Green").theme(GREEN).state(states[1]),
+        layout[1],
+    );
+    frame.render_widget(Button::new("Blue").theme(BLUE).state(states[2]), layout[2]);
+}
+
+fn handle_key_event(
+    key: event::KeyEvent,
+    button_states: &mut [State; 3],
+    selected_button: &mut usize,
+) -> ControlFlow<()> {
+    match key.code {
+        KeyCode::Char('q') => return ControlFlow::Break(()),
+        KeyCode::Left => {
+            button_states[*selected_button] = State::Normal;
+            *selected_button = selected_button.saturating_sub(1);
+            button_states[*selected_button] = State::Selected;
+        }
+        KeyCode::Right => {
+            button_states[*selected_button] = State::Normal;
+            *selected_button = selected_button.saturating_add(1).min(2);
+            button_states[*selected_button] = State::Selected;
+        }
+        KeyCode::Char(' ') => {
+            if button_states[*selected_button] == State::Active {
+                button_states[*selected_button] = State::Normal;
+            } else {
+                button_states[*selected_button] = State::Active;
+            }
+        }
+        _ => (),
+    }
+    ControlFlow::Continue(())
+}
+
+fn handle_mouse_event(
+    mouse: MouseEvent,
+    button_states: &mut [State; 3],
+    selected_button: &mut usize,
+) {
+    match mouse.kind {
+        MouseEventKind::Moved => {
+            let old_selected_button = *selected_button;
+            *selected_button = match mouse.column {
+                x if x < 15 => 0,
+                x if x < 30 => 1,
+                _ => 2,
+            };
+            if old_selected_button != *selected_button {
+                if button_states[old_selected_button] != State::Active {
+                    button_states[old_selected_button] = State::Normal;
+                }
+                if button_states[*selected_button] != State::Active {
+                    button_states[*selected_button] = State::Selected;
+                }
+            }
+        }
+        MouseEventKind::Down(MouseButton::Left) => {
+            if button_states[*selected_button] == State::Active {
+                button_states[*selected_button] = State::Normal;
+            } else {
+                button_states[*selected_button] = State::Active;
+            }
+        }
+        _ => (),
+    }
 }
--- a/examples/custom_widget.tape
+++ b/examples/custom_widget.tape
@@ -0,0 +1,21 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/custom_widget.tape`
+Output "target/custom_widget.gif"
+Set Theme "Aardvark Blue"
+Set Width 760
+Set Height 260
+Hide
+Type "cargo run --example=custom_widget --features=crossterm"
+Enter
+Sleep 2s
+Show
+Sleep 1s
+Set TypingSpeed 0.7s
+Right
+Right
+Space
+Space
+Left
+Space
+Left
+Space
--- a/examples/demo.rs
+++ b/examples/demo.rs
@@ -1,522 +0,0 @@
-#[macro_use]
-extern crate log;
-extern crate stderrlog;
-extern crate termion;
-extern crate tui;
-
-mod util;
-
-use std::io;
-use std::sync::mpsc;
-use std::thread;
-use std::time;
-
-use termion::event;
-use termion::input::TermRead;
-
-use tui::backend::MouseBackend;
-use tui::layout::{Constraint, Direction, Layout, Rect};
-use tui::style::{Color, Modifier, Style};
-use tui::widgets::canvas::{Canvas, Line, Map, MapResolution};
-use tui::widgets::{
-    Axis, BarChart, Block, Borders, Chart, Dataset, Gauge, Item, List, Marker, Paragraph, Row,
-    SelectableList, Sparkline, Table, Tabs, Text, Widget,
-};
-use tui::{Frame, Terminal};
-
-use util::*;
-
-struct Server<'a> {
-    name: &'a str,
-    location: &'a str,
-    coords: (f64, f64),
-    status: &'a str,
-}
-
-struct App<'a> {
-    size: Rect,
-    items: Vec<&'a str>,
-    events: Vec<(&'a str, &'a str)>,
-    selected: usize,
-    tabs: MyTabs<'a>,
-    show_chart: bool,
-    progress: u16,
-    data: Vec<u64>,
-    data2: Vec<(f64, f64)>,
-    data3: Vec<(f64, f64)>,
-    data4: Vec<(&'a str, u64)>,
-    window: [f64; 2],
-    colors: [Color; 2],
-    color_index: usize,
-    servers: Vec<Server<'a>>,
-}
-
-enum Event {
-    Input(event::Key),
-    Tick,
-}
-
-fn main() {
-    stderrlog::new()
-        .module(module_path!())
-        .verbosity(4)
-        .init()
-        .unwrap();
-    info!("Start");
-
-    let mut rand_signal = RandomSignal::new(0, 100);
-    let mut sin_signal = SinSignal::new(0.2, 3.0, 18.0);
-    let mut sin_signal2 = SinSignal::new(0.1, 2.0, 10.0);
-
-    let mut app = App {
-        size: Rect::default(),
-        items: vec![
-            "Item1", "Item2", "Item3", "Item4", "Item5", "Item6", "Item7", "Item8", "Item9",
-            "Item10", "Item11", "Item12", "Item13", "Item14", "Item15", "Item16", "Item17",
-            "Item18", "Item19", "Item20", "Item21", "Item22", "Item23", "Item24",
-        ],
-        events: vec![
-            ("Event1", "INFO"),
-            ("Event2", "INFO"),
-            ("Event3", "CRITICAL"),
-            ("Event4", "ERROR"),
-            ("Event5", "INFO"),
-            ("Event6", "INFO"),
-            ("Event7", "WARNING"),
-            ("Event8", "INFO"),
-            ("Event9", "INFO"),
-            ("Event10", "INFO"),
-            ("Event11", "CRITICAL"),
-            ("Event12", "INFO"),
-            ("Event13", "INFO"),
-            ("Event14", "INFO"),
-            ("Event15", "INFO"),
-            ("Event16", "INFO"),
-            ("Event17", "ERROR"),
-            ("Event18", "ERROR"),
-            ("Event19", "INFO"),
-            ("Event20", "INFO"),
-            ("Event21", "WARNING"),
-            ("Event22", "INFO"),
-            ("Event23", "INFO"),
-            ("Event24", "WARNING"),
-            ("Event25", "INFO"),
-            ("Event26", "INFO"),
-        ],
-        selected: 0,
-        tabs: MyTabs {
-            titles: vec!["Tab0", "Tab1"],
-            selection: 0,
-        },
-        show_chart: true,
-        progress: 0,
-        data: rand_signal.clone().take(300).collect(),
-        data2: sin_signal.clone().take(100).collect(),
-        data3: sin_signal2.clone().take(200).collect(),
-        data4: vec![
-            ("B1", 9),
-            ("B2", 12),
-            ("B3", 5),
-            ("B4", 8),
-            ("B5", 2),
-            ("B6", 4),
-            ("B7", 5),
-            ("B8", 9),
-            ("B9", 14),
-            ("B10", 15),
-            ("B11", 1),
-            ("B12", 0),
-            ("B13", 4),
-            ("B14", 6),
-            ("B15", 4),
-            ("B16", 6),
-            ("B17", 4),
-            ("B18", 7),
-            ("B19", 13),
-            ("B20", 8),
-            ("B21", 11),
-            ("B22", 9),
-            ("B23", 3),
-            ("B24", 5),
-        ],
-        window: [0.0, 20.0],
-        colors: [Color::Magenta, Color::Red],
-        color_index: 0,
-        servers: vec![
-            Server {
-                name: "NorthAmerica-1",
-                location: "New York City",
-                coords: (40.71, -74.00),
-                status: "Up",
-            },
-            Server {
-                name: "Europe-1",
-                location: "Paris",
-                coords: (48.85, 2.35),
-                status: "Failure",
-            },
-            Server {
-                name: "SouthAmerica-1",
-                location: "São Paulo",
-                coords: (-23.54, -46.62),
-                status: "Up",
-            },
-            Server {
-                name: "Asia-1",
-                location: "Singapore",
-                coords: (1.35, 103.86),
-                status: "Up",
-            },
-        ],
-    };
-    let (tx, rx) = mpsc::channel();
-    let input_tx = tx.clone();
-
-    for _ in 0..100 {
-        sin_signal.next();
-    }
-    for _ in 0..200 {
-        sin_signal2.next();
-    }
-
-    thread::spawn(move || {
-        let stdin = io::stdin();
-        for c in stdin.keys() {
-            let evt = c.unwrap();
-            input_tx.send(Event::Input(evt)).unwrap();
-            if evt == event::Key::Char('q') {
-                break;
-            }
-        }
-    });
-
-    thread::spawn(move || {
-        let tx = tx.clone();
-        loop {
-            tx.send(Event::Tick).unwrap();
-            thread::sleep(time::Duration::from_millis(250));
-        }
-    });
-
-    let backend = MouseBackend::new().unwrap();
-    let mut terminal = Terminal::new(backend).unwrap();
-    terminal.clear().unwrap();
-    terminal.hide_cursor().unwrap();
-
-    loop {
-        let size = terminal.size().unwrap();
-        if size != app.size {
-            terminal.resize(size).unwrap();
-            app.size = size;
-        }
-        draw(&mut terminal, &app).unwrap();
-        let evt = rx.recv().unwrap();
-        match evt {
-            Event::Input(input) => match input {
-                event::Key::Char('q') => {
-                    break;
-                }
-                event::Key::Up => {
-                    if app.selected > 0 {
-                        app.selected -= 1
-                    };
-                }
-                event::Key::Down => if app.selected < app.items.len() - 1 {
-                    app.selected += 1;
-                },
-                event::Key::Left => {
-                    app.tabs.previous();
-                }
-                event::Key::Right => {
-                    app.tabs.next();
-                }
-                event::Key::Char('t') => {
-                    app.show_chart = !app.show_chart;
-                }
-                _ => {}
-            },
-            Event::Tick => {
-                app.progress += 5;
-                if app.progress > 100 {
-                    app.progress = 0;
-                }
-                app.data.insert(0, rand_signal.next().unwrap());
-                app.data.pop();
-                for _ in 0..5 {
-                    app.data2.remove(0);
-                    app.data2.push(sin_signal.next().unwrap());
-                }
-                for _ in 0..10 {
-                    app.data3.remove(0);
-                    app.data3.push(sin_signal2.next().unwrap());
-                }
-                let i = app.data4.pop().unwrap();
-                app.data4.insert(0, i);
-                app.window[0] += 1.0;
-                app.window[1] += 1.0;
-                let i = app.events.pop().unwrap();
-                app.events.insert(0, i);
-                app.color_index += 1;
-                if app.color_index >= app.colors.len() {
-                    app.color_index = 0;
-                }
-            }
-        }
-    }
-    terminal.show_cursor().unwrap();
-    terminal.clear().unwrap();
-}
-
-fn draw(t: &mut Terminal<MouseBackend>, app: &App) -> Result<(), io::Error> {
-    t.draw(|mut f| {
-        let chunks = Layout::default()
-            .constraints([Constraint::Length(3), Constraint::Min(0)].as_ref())
-            .split(app.size);
-        Tabs::default()
-            .block(Block::default().borders(Borders::ALL).title("Tabs"))
-            .titles(&app.tabs.titles)
-            .style(Style::default().fg(Color::Green))
-            .highlight_style(Style::default().fg(Color::Yellow))
-            .select(app.tabs.selection)
-            .render(&mut f, chunks[0]);
-        match app.tabs.selection {
-            0 => {
-                draw_first_tab(&mut f, app, chunks[1]);
-            }
-            1 => {
-                draw_second_tab(&mut f, app, chunks[1]);
-            }
-            _ => {}
-        };
-    })
-}
-
-fn draw_first_tab(f: &mut Frame<MouseBackend>, app: &App, area: Rect) {
-    let chunks = Layout::default()
-        .constraints(
-            [
-                Constraint::Length(7),
-                Constraint::Min(7),
-                Constraint::Length(7),
-            ].as_ref(),
-        )
-        .split(area);
-    draw_gauges(f, app, chunks[0]);
-    draw_charts(f, app, chunks[1]);
-    draw_text(f, chunks[2]);
-}
-
-fn draw_gauges(f: &mut Frame<MouseBackend>, app: &App, area: Rect) {
-    let chunks = Layout::default()
-        .constraints([Constraint::Length(2), Constraint::Length(3)].as_ref())
-        .margin(1)
-        .split(area);
-    Block::default()
-        .borders(Borders::ALL)
-        .title("Graphs")
-        .render(f, area);
-    Gauge::default()
-        .block(Block::default().title("Gauge:"))
-        .style(
-            Style::default()
-                .fg(Color::Magenta)
-                .bg(Color::Black)
-                .modifier(Modifier::Italic),
-        )
-        .label(&format!("{} / 100", app.progress))
-        .percent(app.progress)
-        .render(f, chunks[0]);
-    Sparkline::default()
-        .block(Block::default().title("Sparkline:"))
-        .style(Style::default().fg(Color::Green))
-        .data(&app.data)
-        .render(f, chunks[1]);
-}
-
-fn draw_charts(f: &mut Frame<MouseBackend>, app: &App, area: Rect) {
-    let constraints = if app.show_chart {
-        vec![Constraint::Percentage(50), Constraint::Percentage(50)]
-    } else {
-        vec![Constraint::Percentage(100)]
-    };
-    let chunks = Layout::default()
-        .constraints(constraints)
-        .direction(Direction::Horizontal)
-        .split(area);
-    {
-        let chunks = Layout::default()
-            .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-            .split(chunks[0]);
-        {
-            let chunks = Layout::default()
-                .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-                .direction(Direction::Horizontal)
-                .split(chunks[0]);
-            SelectableList::default()
-                .block(Block::default().borders(Borders::ALL).title("List"))
-                .items(&app.items)
-                .select(Some(app.selected))
-                .highlight_style(Style::default().fg(Color::Yellow).modifier(Modifier::Bold))
-                .highlight_symbol(">")
-                .render(f, chunks[0]);
-            let info_style = Style::default().fg(Color::White);
-            let warning_style = Style::default().fg(Color::Yellow);
-            let error_style = Style::default().fg(Color::Magenta);
-            let critical_style = Style::default().fg(Color::Red);
-            let events = app.events.iter().map(|&(evt, level)| {
-                Item::StyledData(
-                    format!("{}: {}", level, evt),
-                    match level {
-                        "ERROR" => &error_style,
-                        "CRITICAL" => &critical_style,
-                        "WARNING" => &warning_style,
-                        _ => &info_style,
-                    },
-                )
-            });
-            List::new(events)
-                .block(Block::default().borders(Borders::ALL).title("List"))
-                .render(f, chunks[1]);
-        }
-        BarChart::default()
-            .block(Block::default().borders(Borders::ALL).title("Bar chart"))
-            .data(&app.data4)
-            .bar_width(3)
-            .bar_gap(2)
-            .value_style(
-                Style::default()
-                    .fg(Color::Black)
-                    .bg(Color::Green)
-                    .modifier(Modifier::Italic),
-            )
-            .label_style(Style::default().fg(Color::Yellow))
-            .style(Style::default().fg(Color::Green))
-            .render(f, chunks[1]);
-    }
-    if app.show_chart {
-        Chart::default()
-            .block(
-                Block::default()
-                    .title("Chart")
-                    .title_style(Style::default().fg(Color::Cyan).modifier(Modifier::Bold))
-                    .borders(Borders::ALL),
-            )
-            .x_axis(
-                Axis::default()
-                    .title("X Axis")
-                    .style(Style::default().fg(Color::Gray))
-                    .labels_style(Style::default().modifier(Modifier::Italic))
-                    .bounds(app.window)
-                    .labels(&[
-                        &format!("{}", app.window[0]),
-                        &format!("{}", (app.window[0] + app.window[1]) / 2.0),
-                        &format!("{}", app.window[1]),
-                    ]),
-            )
-            .y_axis(
-                Axis::default()
-                    .title("Y Axis")
-                    .style(Style::default().fg(Color::Gray))
-                    .labels_style(Style::default().modifier(Modifier::Italic))
-                    .bounds([-20.0, 20.0])
-                    .labels(&["-20", "0", "20"]),
-            )
-            .datasets(&[
-                Dataset::default()
-                    .name("data2")
-                    .marker(Marker::Dot)
-                    .style(Style::default().fg(Color::Cyan))
-                    .data(&app.data2),
-                Dataset::default()
-                    .name("data3")
-                    .marker(Marker::Braille)
-                    .style(Style::default().fg(Color::Yellow))
-                    .data(&app.data3),
-            ])
-            .render(f, chunks[1]);
-    }
-}
-
-fn draw_text(f: &mut Frame<MouseBackend>, area: Rect) {
-    let text = [
-        Text::Data("This is a paragraph with several lines. You can change style your text the way you want.\n\nFox example: "),
-        Text::StyledData("under", Style::default().fg(Color::Red)),
-        Text::Data(" "),
-        Text::StyledData("the", Style::default().fg(Color::Green)),
-        Text::Data(" "),
-        Text::StyledData("rainbow", Style::default().fg(Color::Blue)),
-        Text::Data(".\nOh and if you didn't "),
-        Text::StyledData("notice", Style::default().modifier(Modifier::Italic)),
-        Text::Data(" you can "),
-        Text::StyledData("automatically", Style::default().modifier(Modifier::Bold)),
-        Text::Data(" "),
-        Text::StyledData("wrap", Style::default().modifier(Modifier::Invert)),
-        Text::Data(" your "),
-        Text::StyledData("text", Style::default().modifier(Modifier::Underline)),
-        Text::Data(".\nOne more thing is that it should display unicode characters: 10€")
-    ];
-    Paragraph::new(text.iter())
-        .block(
-            Block::default()
-                .borders(Borders::ALL)
-                .title("Footer")
-                .title_style(Style::default().fg(Color::Magenta).modifier(Modifier::Bold)),
-        )
-        .wrap(true)
-        .render(f, area);
-}
-
-fn draw_second_tab(f: &mut Frame<MouseBackend>, app: &App, area: Rect) {
-    let chunks = Layout::default()
-        .constraints([Constraint::Percentage(30), Constraint::Percentage(70)].as_ref())
-        .direction(Direction::Horizontal)
-        .split(area);
-    let up_style = Style::default().fg(Color::Green);
-    let failure_style = Style::default().fg(Color::Red);
-    Table::new(
-        ["Server", "Location", "Status"].into_iter(),
-        app.servers.iter().map(|s| {
-            let style = if s.status == "Up" {
-                &up_style
-            } else {
-                &failure_style
-            };
-            Row::StyledData(vec![s.name, s.location, s.status].into_iter(), style)
-        }),
-    ).block(Block::default().title("Servers").borders(Borders::ALL))
-        .header_style(Style::default().fg(Color::Yellow))
-        .widths(&[15, 15, 10])
-        .render(f, chunks[0]);
-
-    Canvas::default()
-        .block(Block::default().title("World").borders(Borders::ALL))
-        .paint(|ctx| {
-            ctx.draw(&Map {
-                color: Color::White,
-                resolution: MapResolution::High,
-            });
-            ctx.layer();
-            for (i, s1) in app.servers.iter().enumerate() {
-                for s2 in &app.servers[i + 1..] {
-                    ctx.draw(&Line {
-                        x1: s1.coords.1,
-                        y1: s1.coords.0,
-                        y2: s2.coords.0,
-                        x2: s2.coords.1,
-                        color: Color::Yellow,
-                    });
-                }
-            }
-            for server in &app.servers {
-                let color = if server.status == "Up" {
-                    Color::Green
-                } else {
-                    Color::Red
-                };
-                ctx.print(server.coords.1, server.coords.0, "X", color);
-            }
-        })
-        .x_bounds([-180.0, 180.0])
-        .y_bounds([-90.0, 90.0])
-        .render(f, chunks[1]);
-}
--- a/examples/demo.tape
+++ b/examples/demo.tape
@@ -0,0 +1,18 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/demo.tape`
+Output "target/demo.gif"
+Set Theme "Aardvark Blue"
+Set Width 1200
+Set Height 1200
+Set PlaybackSpeed 0.5
+Hide
+Type "cargo run --example demo"
+Enter
+Sleep 2s
+Show
+Sleep 1s
+Down@1s 12
+Right
+Sleep 4s
+Right
+Sleep 4s
--- a/examples/demo/app.rs
+++ b/examples/demo/app.rs
@@ -0,0 +1,348 @@
+use rand::{
+    distributions::{Distribution, Uniform},
+    rngs::ThreadRng,
+};
+use ratatui::widgets::*;
+
+const TASKS: [&str; 24] = [
+    "Item1", "Item2", "Item3", "Item4", "Item5", "Item6", "Item7", "Item8", "Item9", "Item10",
+    "Item11", "Item12", "Item13", "Item14", "Item15", "Item16", "Item17", "Item18", "Item19",
+    "Item20", "Item21", "Item22", "Item23", "Item24",
+];
+
+const LOGS: [(&str, &str); 26] = [
+    ("Event1", "INFO"),
+    ("Event2", "INFO"),
+    ("Event3", "CRITICAL"),
+    ("Event4", "ERROR"),
+    ("Event5", "INFO"),
+    ("Event6", "INFO"),
+    ("Event7", "WARNING"),
+    ("Event8", "INFO"),
+    ("Event9", "INFO"),
+    ("Event10", "INFO"),
+    ("Event11", "CRITICAL"),
+    ("Event12", "INFO"),
+    ("Event13", "INFO"),
+    ("Event14", "INFO"),
+    ("Event15", "INFO"),
+    ("Event16", "INFO"),
+    ("Event17", "ERROR"),
+    ("Event18", "ERROR"),
+    ("Event19", "INFO"),
+    ("Event20", "INFO"),
+    ("Event21", "WARNING"),
+    ("Event22", "INFO"),
+    ("Event23", "INFO"),
+    ("Event24", "WARNING"),
+    ("Event25", "INFO"),
+    ("Event26", "INFO"),
+];
+
+const EVENTS: [(&str, u64); 24] = [
+    ("B1", 9),
+    ("B2", 12),
+    ("B3", 5),
+    ("B4", 8),
+    ("B5", 2),
+    ("B6", 4),
+    ("B7", 5),
+    ("B8", 9),
+    ("B9", 14),
+    ("B10", 15),
+    ("B11", 1),
+    ("B12", 0),
+    ("B13", 4),
+    ("B14", 6),
+    ("B15", 4),
+    ("B16", 6),
+    ("B17", 4),
+    ("B18", 7),
+    ("B19", 13),
+    ("B20", 8),
+    ("B21", 11),
+    ("B22", 9),
+    ("B23", 3),
+    ("B24", 5),
+];
+
+#[derive(Clone)]
+pub struct RandomSignal {
+    distribution: Uniform<u64>,
+    rng: ThreadRng,
+}
+
+impl RandomSignal {
+    pub fn new(lower: u64, upper: u64) -> RandomSignal {
+        RandomSignal {
+            distribution: Uniform::new(lower, upper),
+            rng: rand::thread_rng(),
+        }
+    }
+}
+
+impl Iterator for RandomSignal {
+    type Item = u64;
+    fn next(&mut self) -> Option<u64> {
+        Some(self.distribution.sample(&mut self.rng))
+    }
+}
+
+#[derive(Clone)]
+pub struct SinSignal {
+    x: f64,
+    interval: f64,
+    period: f64,
+    scale: f64,
+}
+
+impl SinSignal {
+    pub fn new(interval: f64, period: f64, scale: f64) -> SinSignal {
+        SinSignal {
+            x: 0.0,
+            interval,
+            period,
+            scale,
+        }
+    }
+}
+
+impl Iterator for SinSignal {
+    type Item = (f64, f64);
+    fn next(&mut self) -> Option<Self::Item> {
+        let point = (self.x, (self.x * 1.0 / self.period).sin() * self.scale);
+        self.x += self.interval;
+        Some(point)
+    }
+}
+
+pub struct TabsState<'a> {
+    pub titles: Vec<&'a str>,
+    pub index: usize,
+}
+
+impl<'a> TabsState<'a> {
+    pub fn new(titles: Vec<&'a str>) -> TabsState {
+        TabsState { titles, index: 0 }
+    }
+    pub fn next(&mut self) {
+        self.index = (self.index + 1) % self.titles.len();
+    }
+
+    pub fn previous(&mut self) {
+        if self.index > 0 {
+            self.index -= 1;
+        } else {
+            self.index = self.titles.len() - 1;
+        }
+    }
+}
+
+pub struct StatefulList<T> {
+    pub state: ListState,
+    pub items: Vec<T>,
+}
+
+impl<T> StatefulList<T> {
+    pub fn with_items(items: Vec<T>) -> StatefulList<T> {
+        StatefulList {
+            state: ListState::default(),
+            items,
+        }
+    }
+
+    pub fn next(&mut self) {
+        let i = match self.state.selected() {
+            Some(i) => {
+                if i >= self.items.len() - 1 {
+                    0
+                } else {
+                    i + 1
+                }
+            }
+            None => 0,
+        };
+        self.state.select(Some(i));
+    }
+
+    pub fn previous(&mut self) {
+        let i = match self.state.selected() {
+            Some(i) => {
+                if i == 0 {
+                    self.items.len() - 1
+                } else {
+                    i - 1
+                }
+            }
+            None => 0,
+        };
+        self.state.select(Some(i));
+    }
+}
+
+pub struct Signal<S: Iterator> {
+    source: S,
+    pub points: Vec<S::Item>,
+    tick_rate: usize,
+}
+
+impl<S> Signal<S>
+where
+    S: Iterator,
+{
+    fn on_tick(&mut self) {
+        for _ in 0..self.tick_rate {
+            self.points.remove(0);
+        }
+        self.points
+            .extend(self.source.by_ref().take(self.tick_rate));
+    }
+}
+
+pub struct Signals {
+    pub sin1: Signal<SinSignal>,
+    pub sin2: Signal<SinSignal>,
+    pub window: [f64; 2],
+}
+
+impl Signals {
+    fn on_tick(&mut self) {
+        self.sin1.on_tick();
+        self.sin2.on_tick();
+        self.window[0] += 1.0;
+        self.window[1] += 1.0;
+    }
+}
+
+pub struct Server<'a> {
+    pub name: &'a str,
+    pub location: &'a str,
+    pub coords: (f64, f64),
+    pub status: &'a str,
+}
+
+pub struct App<'a> {
+    pub title: &'a str,
+    pub should_quit: bool,
+    pub tabs: TabsState<'a>,
+    pub show_chart: bool,
+    pub progress: f64,
+    pub sparkline: Signal<RandomSignal>,
+    pub tasks: StatefulList<&'a str>,
+    pub logs: StatefulList<(&'a str, &'a str)>,
+    pub signals: Signals,
+    pub barchart: Vec<(&'a str, u64)>,
+    pub servers: Vec<Server<'a>>,
+    pub enhanced_graphics: bool,
+}
+
+impl<'a> App<'a> {
+    pub fn new(title: &'a str, enhanced_graphics: bool) -> App<'a> {
+        let mut rand_signal = RandomSignal::new(0, 100);
+        let sparkline_points = rand_signal.by_ref().take(300).collect();
+        let mut sin_signal = SinSignal::new(0.2, 3.0, 18.0);
+        let sin1_points = sin_signal.by_ref().take(100).collect();
+        let mut sin_signal2 = SinSignal::new(0.1, 2.0, 10.0);
+        let sin2_points = sin_signal2.by_ref().take(200).collect();
+        App {
+            title,
+            should_quit: false,
+            tabs: TabsState::new(vec!["Tab0", "Tab1", "Tab2"]),
+            show_chart: true,
+            progress: 0.0,
+            sparkline: Signal {
+                source: rand_signal,
+                points: sparkline_points,
+                tick_rate: 1,
+            },
+            tasks: StatefulList::with_items(TASKS.to_vec()),
+            logs: StatefulList::with_items(LOGS.to_vec()),
+            signals: Signals {
+                sin1: Signal {
+                    source: sin_signal,
+                    points: sin1_points,
+                    tick_rate: 5,
+                },
+                sin2: Signal {
+                    source: sin_signal2,
+                    points: sin2_points,
+                    tick_rate: 10,
+                },
+                window: [0.0, 20.0],
+            },
+            barchart: EVENTS.to_vec(),
+            servers: vec![
+                Server {
+                    name: "NorthAmerica-1",
+                    location: "New York City",
+                    coords: (40.71, -74.00),
+                    status: "Up",
+                },
+                Server {
+                    name: "Europe-1",
+                    location: "Paris",
+                    coords: (48.85, 2.35),
+                    status: "Failure",
+                },
+                Server {
+                    name: "SouthAmerica-1",
+                    location: "São Paulo",
+                    coords: (-23.54, -46.62),
+                    status: "Up",
+                },
+                Server {
+                    name: "Asia-1",
+                    location: "Singapore",
+                    coords: (1.35, 103.86),
+                    status: "Up",
+                },
+            ],
+            enhanced_graphics,
+        }
+    }
+
+    pub fn on_up(&mut self) {
+        self.tasks.previous();
+    }
+
+    pub fn on_down(&mut self) {
+        self.tasks.next();
+    }
+
+    pub fn on_right(&mut self) {
+        self.tabs.next();
+    }
+
+    pub fn on_left(&mut self) {
+        self.tabs.previous();
+    }
+
+    pub fn on_key(&mut self, c: char) {
+        match c {
+            'q' => {
+                self.should_quit = true;
+            }
+            't' => {
+                self.show_chart = !self.show_chart;
+            }
+            _ => {}
+        }
+    }
+
+    pub fn on_tick(&mut self) {
+        // Update progress
+        self.progress += 0.001;
+        if self.progress > 1.0 {
+            self.progress = 0.0;
+        }
+
+        self.sparkline.on_tick();
+        self.signals.on_tick();
+
+        let log = self.logs.items.pop().unwrap();
+        self.logs.items.insert(0, log);
+
+        let event = self.barchart.pop().unwrap();
+        self.barchart.insert(0, event);
+    }
+}
--- a/examples/demo/crossterm.rs
+++ b/examples/demo/crossterm.rs
@@ -0,0 +1,76 @@
+use std::{
+    error::Error,
+    io,
+    time::{Duration, Instant},
+};
+
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::prelude::*;
+
+use crate::{app::App, ui};
+
+pub fn run(tick_rate: Duration, enhanced_graphics: bool) -> Result<(), Box<dyn Error>> {
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+
+    // create app and run it
+    let app = App::new("Crossterm Demo", enhanced_graphics);
+    let res = run_app(&mut terminal, app, tick_rate);
+
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
+
+    if let Err(err) = res {
+        println!("{err:?}");
+    }
+
+    Ok(())
+}
+
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    mut app: App,
+    tick_rate: Duration,
+) -> io::Result<()> {
+    let mut last_tick = Instant::now();
+    loop {
+        terminal.draw(|f| ui::draw(f, &mut app))?;
+
+        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+        if crossterm::event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                if key.kind == KeyEventKind::Press {
+                    match key.code {
+                        KeyCode::Char(c) => app.on_key(c),
+                        KeyCode::Left => app.on_left(),
+                        KeyCode::Up => app.on_up(),
+                        KeyCode::Right => app.on_right(),
+                        KeyCode::Down => app.on_down(),
+                        _ => {}
+                    }
+                }
+            }
+        }
+        if last_tick.elapsed() >= tick_rate {
+            app.on_tick();
+            last_tick = Instant::now();
+        }
+        if app.should_quit {
+            return Ok(());
+        }
+    }
+}
--- a/examples/demo/main.rs
+++ b/examples/demo/main.rs
@@ -0,0 +1,36 @@
+use std::{error::Error, time::Duration};
+
+use argh::FromArgs;
+
+mod app;
+#[cfg(feature = "crossterm")]
+mod crossterm;
+#[cfg(feature = "termion")]
+mod termion;
+#[cfg(feature = "termwiz")]
+mod termwiz;
+
+mod ui;
+
+/// Demo
+#[derive(Debug, FromArgs)]
+struct Cli {
+    /// time in ms between two ticks.
+    #[argh(option, default = "250")]
+    tick_rate: u64,
+    /// whether unicode symbols are used to improve the overall look of the app
+    #[argh(option, default = "true")]
+    enhanced_graphics: bool,
+}
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let cli: Cli = argh::from_env();
+    let tick_rate = Duration::from_millis(cli.tick_rate);
+    #[cfg(feature = "crossterm")]
+    crate::crossterm::run(tick_rate, cli.enhanced_graphics)?;
+    #[cfg(feature = "termion")]
+    crate::termion::run(tick_rate, cli.enhanced_graphics)?;
+    #[cfg(feature = "termwiz")]
+    crate::termwiz::run(tick_rate, cli.enhanced_graphics)?;
+    Ok(())
+}
--- a/examples/demo/termion.rs
+++ b/examples/demo/termion.rs
@@ -0,0 +1,82 @@
+use std::{error::Error, io, sync::mpsc, thread, time::Duration};
+
+use ratatui::prelude::*;
+use termion::{
+    event::Key,
+    input::{MouseTerminal, TermRead},
+    raw::IntoRawMode,
+    screen::IntoAlternateScreen,
+};
+
+use crate::{app::App, ui};
+
+pub fn run(tick_rate: Duration, enhanced_graphics: bool) -> Result<(), Box<dyn Error>> {
+    // setup terminal
+    let stdout = io::stdout()
+        .into_raw_mode()
+        .unwrap()
+        .into_alternate_screen()
+        .unwrap();
+    let stdout = MouseTerminal::from(stdout);
+    let backend = TermionBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+
+    // create app and run it
+    let app = App::new("Termion demo", enhanced_graphics);
+    run_app(&mut terminal, app, tick_rate)?;
+
+    Ok(())
+}
+
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    mut app: App,
+    tick_rate: Duration,
+) -> Result<(), Box<dyn Error>> {
+    let events = events(tick_rate);
+    loop {
+        terminal.draw(|f| ui::draw(f, &mut app))?;
+
+        match events.recv()? {
+            Event::Input(key) => match key {
+                Key::Char(c) => app.on_key(c),
+                Key::Up => app.on_up(),
+                Key::Down => app.on_down(),
+                Key::Left => app.on_left(),
+                Key::Right => app.on_right(),
+                _ => {}
+            },
+            Event::Tick => app.on_tick(),
+        }
+        if app.should_quit {
+            return Ok(());
+        }
+    }
+}
+
+enum Event {
+    Input(Key),
+    Tick,
+}
+
+fn events(tick_rate: Duration) -> mpsc::Receiver<Event> {
+    let (tx, rx) = mpsc::channel();
+    let keys_tx = tx.clone();
+    thread::spawn(move || {
+        let stdin = io::stdin();
+        for key in stdin.keys().flatten() {
+            if let Err(err) = keys_tx.send(Event::Input(key)) {
+                eprintln!("{err}");
+                return;
+            }
+        }
+    });
+    thread::spawn(move || loop {
+        if let Err(err) = tx.send(Event::Tick) {
+            eprintln!("{err}");
+            break;
+        }
+        thread::sleep(tick_rate);
+    });
+    rx
+}
--- a/examples/demo/termwiz.rs
+++ b/examples/demo/termwiz.rs
@@ -0,0 +1,73 @@
+use std::{
+    error::Error,
+    time::{Duration, Instant},
+};
+
+use ratatui::prelude::*;
+use termwiz::{input::*, terminal::Terminal as TermwizTerminal};
+
+use crate::{app::App, ui};
+
+pub fn run(tick_rate: Duration, enhanced_graphics: bool) -> Result<(), Box<dyn Error>> {
+    let backend = TermwizBackend::new()?;
+    let mut terminal = Terminal::new(backend)?;
+    terminal.hide_cursor()?;
+
+    // create app and run it
+    let app = App::new("Termwiz Demo", enhanced_graphics);
+    let res = run_app(&mut terminal, app, tick_rate);
+
+    terminal.show_cursor()?;
+    terminal.flush()?;
+
+    if let Err(err) = res {
+        println!("{err:?}");
+    }
+
+    Ok(())
+}
+
+fn run_app(
+    terminal: &mut Terminal<TermwizBackend>,
+    mut app: App,
+    tick_rate: Duration,
+) -> Result<(), Box<dyn Error>> {
+    let mut last_tick = Instant::now();
+    loop {
+        terminal.draw(|f| ui::draw(f, &mut app))?;
+
+        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+        if let Some(input) = terminal
+            .backend_mut()
+            .buffered_terminal_mut()
+            .terminal()
+            .poll_input(Some(timeout))?
+        {
+            match input {
+                InputEvent::Key(key_code) => match key_code.key {
+                    KeyCode::UpArrow => app.on_up(),
+                    KeyCode::DownArrow => app.on_down(),
+                    KeyCode::LeftArrow => app.on_left(),
+                    KeyCode::RightArrow => app.on_right(),
+                    KeyCode::Char(c) => app.on_key(c),
+                    _ => {}
+                },
+                InputEvent::Resized { cols, rows } => {
+                    terminal
+                        .backend_mut()
+                        .buffered_terminal_mut()
+                        .resize(cols, rows);
+                }
+                _ => {}
+            }
+        }
+
+        if last_tick.elapsed() >= tick_rate {
+            app.on_tick();
+            last_tick = Instant::now();
+        }
+        if app.should_quit {
+            return Ok(());
+        }
+    }
+}
--- a/examples/demo/ui.rs
+++ b/examples/demo/ui.rs
@@ -0,0 +1,404 @@
+use ratatui::{
+    prelude::*,
+    widgets::{canvas::*, *},
+};
+
+use crate::app::App;
+
+pub fn draw(f: &mut Frame, app: &mut App) {
+    let chunks = Layout::default()
+        .constraints([Constraint::Length(3), Constraint::Min(0)])
+        .split(f.size());
+    let titles = app
+        .tabs
+        .titles
+        .iter()
+        .map(|t| text::Line::from(Span::styled(*t, Style::default().fg(Color::Green))))
+        .collect();
+    let tabs = Tabs::new(titles)
+        .block(Block::default().borders(Borders::ALL).title(app.title))
+        .highlight_style(Style::default().fg(Color::Yellow))
+        .select(app.tabs.index);
+    f.render_widget(tabs, chunks[0]);
+    match app.tabs.index {
+        0 => draw_first_tab(f, app, chunks[1]),
+        1 => draw_second_tab(f, app, chunks[1]),
+        2 => draw_third_tab(f, app, chunks[1]),
+        _ => {}
+    };
+}
+
+fn draw_first_tab(f: &mut Frame, app: &mut App, area: Rect) {
+    let chunks = Layout::default()
+        .constraints([
+            Constraint::Length(9),
+            Constraint::Min(8),
+            Constraint::Length(7),
+        ])
+        .split(area);
+    draw_gauges(f, app, chunks[0]);
+    draw_charts(f, app, chunks[1]);
+    draw_text(f, chunks[2]);
+}
+
+fn draw_gauges(f: &mut Frame, app: &mut App, area: Rect) {
+    let chunks = Layout::default()
+        .constraints([
+            Constraint::Length(2),
+            Constraint::Length(3),
+            Constraint::Length(1),
+        ])
+        .margin(1)
+        .split(area);
+    let block = Block::default().borders(Borders::ALL).title("Graphs");
+    f.render_widget(block, area);
+
+    let label = format!("{:.2}%", app.progress * 100.0);
+    let gauge = Gauge::default()
+        .block(Block::default().title("Gauge:"))
+        .gauge_style(
+            Style::default()
+                .fg(Color::Magenta)
+                .bg(Color::Black)
+                .add_modifier(Modifier::ITALIC | Modifier::BOLD),
+        )
+        .use_unicode(app.enhanced_graphics)
+        .label(label)
+        .ratio(app.progress);
+    f.render_widget(gauge, chunks[0]);
+
+    let sparkline = Sparkline::default()
+        .block(Block::default().title("Sparkline:"))
+        .style(Style::default().fg(Color::Green))
+        .data(&app.sparkline.points)
+        .bar_set(if app.enhanced_graphics {
+            symbols::bar::NINE_LEVELS
+        } else {
+            symbols::bar::THREE_LEVELS
+        });
+    f.render_widget(sparkline, chunks[1]);
+
+    let line_gauge = LineGauge::default()
+        .block(Block::default().title("LineGauge:"))
+        .gauge_style(Style::default().fg(Color::Magenta))
+        .line_set(if app.enhanced_graphics {
+            symbols::line::THICK
+        } else {
+            symbols::line::NORMAL
+        })
+        .ratio(app.progress);
+    f.render_widget(line_gauge, chunks[2]);
+}
+
+fn draw_charts(f: &mut Frame, app: &mut App, area: Rect) {
+    let constraints = if app.show_chart {
+        vec![Constraint::Percentage(50), Constraint::Percentage(50)]
+    } else {
+        vec![Constraint::Percentage(100)]
+    };
+    let chunks = Layout::default()
+        .constraints(constraints)
+        .direction(Direction::Horizontal)
+        .split(area);
+    {
+        let chunks = Layout::default()
+            .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
+            .split(chunks[0]);
+        {
+            let chunks = Layout::default()
+                .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
+                .direction(Direction::Horizontal)
+                .split(chunks[0]);
+
+            // Draw tasks
+            let tasks: Vec<ListItem> = app
+                .tasks
+                .items
+                .iter()
+                .map(|i| ListItem::new(vec![text::Line::from(Span::raw(*i))]))
+                .collect();
+            let tasks = List::new(tasks)
+                .block(Block::default().borders(Borders::ALL).title("List"))
+                .highlight_style(Style::default().add_modifier(Modifier::BOLD))
+                .highlight_symbol("> ");
+            f.render_stateful_widget(tasks, chunks[0], &mut app.tasks.state);
+
+            // Draw logs
+            let info_style = Style::default().fg(Color::Blue);
+            let warning_style = Style::default().fg(Color::Yellow);
+            let error_style = Style::default().fg(Color::Magenta);
+            let critical_style = Style::default().fg(Color::Red);
+            let logs: Vec<ListItem> = app
+                .logs
+                .items
+                .iter()
+                .map(|&(evt, level)| {
+                    let s = match level {
+                        "ERROR" => error_style,
+                        "CRITICAL" => critical_style,
+                        "WARNING" => warning_style,
+                        _ => info_style,
+                    };
+                    let content = vec![text::Line::from(vec![
+                        Span::styled(format!("{level:<9}"), s),
+                        Span::raw(evt),
+                    ])];
+                    ListItem::new(content)
+                })
+                .collect();
+            let logs = List::new(logs).block(Block::default().borders(Borders::ALL).title("List"));
+            f.render_stateful_widget(logs, chunks[1], &mut app.logs.state);
+        }
+
+        let barchart = BarChart::default()
+            .block(Block::default().borders(Borders::ALL).title("Bar chart"))
+            .data(&app.barchart)
+            .bar_width(3)
+            .bar_gap(2)
+            .bar_set(if app.enhanced_graphics {
+                symbols::bar::NINE_LEVELS
+            } else {
+                symbols::bar::THREE_LEVELS
+            })
+            .value_style(
+                Style::default()
+                    .fg(Color::Black)
+                    .bg(Color::Green)
+                    .add_modifier(Modifier::ITALIC),
+            )
+            .label_style(Style::default().fg(Color::Yellow))
+            .bar_style(Style::default().fg(Color::Green));
+        f.render_widget(barchart, chunks[1]);
+    }
+    if app.show_chart {
+        let x_labels = vec![
+            Span::styled(
+                format!("{}", app.signals.window[0]),
+                Style::default().add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(format!(
+                "{}",
+                (app.signals.window[0] + app.signals.window[1]) / 2.0
+            )),
+            Span::styled(
+                format!("{}", app.signals.window[1]),
+                Style::default().add_modifier(Modifier::BOLD),
+            ),
+        ];
+        let datasets = vec![
+            Dataset::default()
+                .name("data2")
+                .marker(symbols::Marker::Dot)
+                .style(Style::default().fg(Color::Cyan))
+                .data(&app.signals.sin1.points),
+            Dataset::default()
+                .name("data3")
+                .marker(if app.enhanced_graphics {
+                    symbols::Marker::Braille
+                } else {
+                    symbols::Marker::Dot
+                })
+                .style(Style::default().fg(Color::Yellow))
+                .data(&app.signals.sin2.points),
+        ];
+        let chart = Chart::new(datasets)
+            .block(
+                Block::default()
+                    .title(Span::styled(
+                        "Chart",
+                        Style::default()
+                            .fg(Color::Cyan)
+                            .add_modifier(Modifier::BOLD),
+                    ))
+                    .borders(Borders::ALL),
+            )
+            .x_axis(
+                Axis::default()
+                    .title("X Axis")
+                    .style(Style::default().fg(Color::Gray))
+                    .bounds(app.signals.window)
+                    .labels(x_labels),
+            )
+            .y_axis(
+                Axis::default()
+                    .title("Y Axis")
+                    .style(Style::default().fg(Color::Gray))
+                    .bounds([-20.0, 20.0])
+                    .labels(vec![
+                        Span::styled("-20", Style::default().add_modifier(Modifier::BOLD)),
+                        Span::raw("0"),
+                        Span::styled("20", Style::default().add_modifier(Modifier::BOLD)),
+                    ]),
+            );
+        f.render_widget(chart, chunks[1]);
+    }
+}
+
+fn draw_text(f: &mut Frame, area: Rect) {
+    let text = vec![
+        text::Line::from("This is a paragraph with several lines. You can change style your text the way you want"),
+        text::Line::from(""),
+        text::Line::from(vec![
+            Span::from("For example: "),
+            Span::styled("under", Style::default().fg(Color::Red)),
+            Span::raw(" "),
+            Span::styled("the", Style::default().fg(Color::Green)),
+            Span::raw(" "),
+            Span::styled("rainbow", Style::default().fg(Color::Blue)),
+            Span::raw("."),
+        ]),
+        text::Line::from(vec![
+            Span::raw("Oh and if you didn't "),
+            Span::styled("notice", Style::default().add_modifier(Modifier::ITALIC)),
+            Span::raw(" you can "),
+            Span::styled("automatically", Style::default().add_modifier(Modifier::BOLD)),
+            Span::raw(" "),
+            Span::styled("wrap", Style::default().add_modifier(Modifier::REVERSED)),
+            Span::raw(" your "),
+            Span::styled("text", Style::default().add_modifier(Modifier::UNDERLINED)),
+            Span::raw(".")
+        ]),
+        text::Line::from(
+            "One more thing is that it should display unicode characters: 10€"
+        ),
+    ];
+    let block = Block::default().borders(Borders::ALL).title(Span::styled(
+        "Footer",
+        Style::default()
+            .fg(Color::Magenta)
+            .add_modifier(Modifier::BOLD),
+    ));
+    let paragraph = Paragraph::new(text).block(block).wrap(Wrap { trim: true });
+    f.render_widget(paragraph, area);
+}
+
+fn draw_second_tab(f: &mut Frame, app: &mut App, area: Rect) {
+    let chunks = Layout::default()
+        .constraints([Constraint::Percentage(30), Constraint::Percentage(70)])
+        .direction(Direction::Horizontal)
+        .split(area);
+    let up_style = Style::default().fg(Color::Green);
+    let failure_style = Style::default()
+        .fg(Color::Red)
+        .add_modifier(Modifier::RAPID_BLINK | Modifier::CROSSED_OUT);
+    let rows = app.servers.iter().map(|s| {
+        let style = if s.status == "Up" {
+            up_style
+        } else {
+            failure_style
+        };
+        Row::new(vec![s.name, s.location, s.status]).style(style)
+    });
+    let table = Table::new(rows)
+        .header(
+            Row::new(vec!["Server", "Location", "Status"])
+                .style(Style::default().fg(Color::Yellow))
+                .bottom_margin(1),
+        )
+        .block(Block::default().title("Servers").borders(Borders::ALL))
+        .widths(&[
+            Constraint::Length(15),
+            Constraint::Length(15),
+            Constraint::Length(10),
+        ]);
+    f.render_widget(table, chunks[0]);
+
+    let map = Canvas::default()
+        .block(Block::default().title("World").borders(Borders::ALL))
+        .paint(|ctx| {
+            ctx.draw(&Map {
+                color: Color::White,
+                resolution: MapResolution::High,
+            });
+            ctx.layer();
+            ctx.draw(&Rectangle {
+                x: 0.0,
+                y: 30.0,
+                width: 10.0,
+                height: 10.0,
+                color: Color::Yellow,
+            });
+            ctx.draw(&Circle {
+                x: app.servers[2].coords.1,
+                y: app.servers[2].coords.0,
+                radius: 10.0,
+                color: Color::Green,
+            });
+            for (i, s1) in app.servers.iter().enumerate() {
+                for s2 in &app.servers[i + 1..] {
+                    ctx.draw(&canvas::Line {
+                        x1: s1.coords.1,
+                        y1: s1.coords.0,
+                        y2: s2.coords.0,
+                        x2: s2.coords.1,
+                        color: Color::Yellow,
+                    });
+                }
+            }
+            for server in &app.servers {
+                let color = if server.status == "Up" {
+                    Color::Green
+                } else {
+                    Color::Red
+                };
+                ctx.print(
+                    server.coords.1,
+                    server.coords.0,
+                    Span::styled("X", Style::default().fg(color)),
+                );
+            }
+        })
+        .marker(if app.enhanced_graphics {
+            symbols::Marker::Braille
+        } else {
+            symbols::Marker::Dot
+        })
+        .x_bounds([-180.0, 180.0])
+        .y_bounds([-90.0, 90.0]);
+    f.render_widget(map, chunks[1]);
+}
+
+fn draw_third_tab(f: &mut Frame, _app: &mut App, area: Rect) {
+    let chunks = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)])
+        .split(area);
+    let colors = [
+        Color::Reset,
+        Color::Black,
+        Color::Red,
+        Color::Green,
+        Color::Yellow,
+        Color::Blue,
+        Color::Magenta,
+        Color::Cyan,
+        Color::Gray,
+        Color::DarkGray,
+        Color::LightRed,
+        Color::LightGreen,
+        Color::LightYellow,
+        Color::LightBlue,
+        Color::LightMagenta,
+        Color::LightCyan,
+        Color::White,
+    ];
+    let items: Vec<Row> = colors
+        .iter()
+        .map(|c| {
+            let cells = vec![
+                Cell::from(Span::raw(format!("{c:?}: "))),
+                Cell::from(Span::styled("Foreground", Style::default().fg(*c))),
+                Cell::from(Span::styled("Background", Style::default().bg(*c))),
+            ];
+            Row::new(cells)
+        })
+        .collect();
+    let table = Table::new(items)
+        .block(Block::default().title("Colors").borders(Borders::ALL))
+        .widths(&[
+            Constraint::Ratio(1, 3),
+            Constraint::Ratio(1, 3),
+            Constraint::Ratio(1, 3),
+        ]);
+    f.render_widget(table, chunks[0]);
+}
--- a/examples/demo2-social.tape
+++ b/examples/demo2-social.tape
@@ -0,0 +1,43 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/demo.tape`
+
+Output "target/demo2-social.gif"
+Set Theme "Aardvark Blue"
+# Github social preview size (1280x640 with 80px padding) and must be < 1MB
+# This puts some constraints on the amount of interactivity we can do.
+Set Width 1280
+Set Height 640
+Set Padding 80
+Hide
+Type "cargo run --example demo2 --features crossterm,widget-calendar"
+Enter
+Sleep 2s
+Show
+# About screen
+Sleep 3.5s
+Down # Red eye
+Sleep 0.4s
+Down # black eye
+Sleep 1s
+Tab
+# Recipe
+Sleep 1s
+Set TypingSpeed 500ms
+Down 7
+Sleep 1s
+Tab
+# Email
+Sleep 2s
+Down 4
+Sleep 2s
+Tab
+# Trace route
+Sleep 1s
+Set TypingSpeed 200ms
+Down 10
+Sleep 2s
+Tab
+# Weather
+Set TypingSpeed 100ms
+Down 40
+Sleep 2s
--- a/examples/demo2.tape
+++ b/examples/demo2.tape
@@ -0,0 +1,49 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/demo.tape`
+# NOTE: Requires VHS 0.6.1 or later for Screenshot support
+Output "target/demo2.gif"
+Set Theme "Aardvark Blue"
+# The reason for this strange size is that the social preview image for this
+# demo is 1280x64 with 80 pixels of padding on each side. We want a version
+# without the padding for README.md, etc.
+Set Width 1120
+Set Height 480
+Set Padding 0
+Hide
+Type "cargo run --example demo2 --features crossterm,widget-calendar"
+Enter
+Sleep 2s
+Show
+# About screen
+Screenshot "target/demo2-about.png"
+Sleep 3.5s
+Down # Red eye
+Sleep 0.4s
+Down # black eye
+Sleep 1s
+Tab
+# Recipe
+Screenshot "target/demo2-recipe.png"
+Sleep 1s
+Set TypingSpeed 500ms
+Down 7
+Sleep 1s
+Tab
+# Email
+Screenshot "target/demo2-email.png"
+Sleep 2s
+Down 4
+Sleep 2s
+Tab
+# Trace route
+Screenshot "target/demo2-trace.png"
+Sleep 1s
+Set TypingSpeed 200ms
+Down 10
+Sleep 2s
+Tab
+# Weather
+Screenshot "target/demo2-weather.png"
+Set TypingSpeed 100ms
+Down 40
+Sleep 2s
--- a/examples/demo2/app.rs
+++ b/examples/demo2/app.rs
@@ -0,0 +1,99 @@
+use std::time::Duration;
+
+use anyhow::{Context, Result};
+use crossterm::event::{Event, KeyCode, KeyEvent, KeyEventKind, KeyModifiers};
+use ratatui::prelude::Rect;
+
+use crate::{Root, Term};
+
+#[derive(Debug)]
+pub struct App {
+    term: Term,
+    should_quit: bool,
+    context: AppContext,
+}
+
+#[derive(Debug, Default, Clone, Copy)]
+pub struct AppContext {
+    pub tab_index: usize,
+    pub row_index: usize,
+}
+
+impl App {
+    fn new() -> Result<Self> {
+        Ok(Self {
+            term: Term::start()?,
+            should_quit: false,
+            context: AppContext::default(),
+        })
+    }
+
+    pub fn run() -> Result<()> {
+        install_panic_hook();
+        let mut app = Self::new()?;
+        while !app.should_quit {
+            app.draw()?;
+            app.handle_events()?;
+        }
+        Term::stop()?;
+        Ok(())
+    }
+
+    fn draw(&mut self) -> Result<()> {
+        self.term
+            .draw(|frame| frame.render_widget(Root::new(&self.context), frame.size()))
+            .context("terminal.draw")?;
+        Ok(())
+    }
+
+    fn handle_events(&mut self) -> Result<()> {
+        match Term::next_event(Duration::from_millis(16))? {
+            Some(Event::Key(key)) => self.handle_key_event(key),
+            Some(Event::Resize(width, height)) => {
+                Ok(self.term.resize(Rect::new(0, 0, width, height))?)
+            }
+            _ => Ok(()),
+        }
+    }
+
+    fn handle_key_event(&mut self, key: KeyEvent) -> Result<()> {
+        if key.kind != KeyEventKind::Press {
+            return Ok(());
+        }
+
+        let context = &mut self.context;
+        const TAB_COUNT: usize = 5;
+        match key.code {
+            KeyCode::Char('q') | KeyCode::Esc => {
+                self.should_quit = true;
+            }
+            KeyCode::Tab | KeyCode::BackTab if key.modifiers.contains(KeyModifiers::SHIFT) => {
+                let tab_index = context.tab_index + TAB_COUNT; // to wrap around properly
+                context.tab_index = tab_index.saturating_sub(1) % TAB_COUNT;
+                context.row_index = 0;
+            }
+            KeyCode::Tab | KeyCode::BackTab => {
+                context.tab_index = context.tab_index.saturating_add(1) % TAB_COUNT;
+                context.row_index = 0;
+            }
+            KeyCode::Up | KeyCode::Char('k') => {
+                context.row_index = context.row_index.saturating_sub(1);
+            }
+            KeyCode::Down | KeyCode::Char('j') => {
+                context.row_index = context.row_index.saturating_add(1);
+            }
+            _ => {}
+        };
+        Ok(())
+    }
+}
+
+pub fn install_panic_hook() {
+    better_panic::install();
+    let hook = std::panic::take_hook();
+    std::panic::set_hook(Box::new(move |info| {
+        let _ = Term::stop();
+        hook(info);
+        std::process::exit(1);
+    }));
+}
--- a/examples/demo2/colors.rs
+++ b/examples/demo2/colors.rs
@@ -0,0 +1,34 @@
+use palette::{IntoColor, Okhsv, Srgb};
+use ratatui::{prelude::*, widgets::*};
+
+/// A widget that renders a color swatch of RGB colors.
+///
+/// The widget is rendered as a rectangle with the hue changing along the x-axis from 0.0 to 360.0
+/// and the value changing along the y-axis (from 1.0 to 0.0). Each pixel is rendered as a block
+/// character with the top half slightly lighter than the bottom half.
+pub struct RgbSwatch;
+
+impl Widget for RgbSwatch {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        for (yi, y) in (area.top()..area.bottom()).enumerate() {
+            let value = area.height as f32 - yi as f32;
+            let value_fg = value / (area.height as f32);
+            let value_bg = (value - 0.5) / (area.height as f32);
+            for (xi, x) in (area.left()..area.right()).enumerate() {
+                let hue = xi as f32 * 360.0 / area.width as f32;
+                let fg = color_from_oklab(hue, Okhsv::max_saturation(), value_fg);
+                let bg = color_from_oklab(hue, Okhsv::max_saturation(), value_bg);
+                buf.get_mut(x, y).set_char('▀').set_fg(fg).set_bg(bg);
+            }
+        }
+    }
+}
+
+/// Convert a hue and value into an RGB color via the OkLab color space.
+///
+/// See <https://bottosson.github.io/posts/oklab/> for more details.
+pub fn color_from_oklab(hue: f32, saturation: f32, value: f32) -> Color {
+    let color: Srgb = Okhsv::new(hue, saturation, value).into_color();
+    let color = color.into_format();
+    Color::Rgb(color.red, color.green, color.blue)
+}
--- a/examples/demo2/main.rs
+++ b/examples/demo2/main.rs
@@ -0,0 +1,17 @@
+use anyhow::Result;
+pub use app::*;
+pub use colors::*;
+pub use root::*;
+pub use term::*;
+pub use theme::*;
+
+mod app;
+mod colors;
+mod root;
+mod tabs;
+mod term;
+mod theme;
+
+fn main() -> Result<()> {
+    App::run()
+}
--- a/examples/demo2/root.rs
+++ b/examples/demo2/root.rs
@@ -0,0 +1,93 @@
+use std::rc::Rc;
+
+use itertools::Itertools;
+use ratatui::{prelude::*, widgets::*};
+
+use crate::{tabs::*, AppContext, THEME};
+
+pub struct Root<'a> {
+    context: &'a AppContext,
+}
+
+impl<'a> Root<'a> {
+    pub fn new(context: &'a AppContext) -> Self {
+        Root { context }
+    }
+}
+
+impl Widget for Root<'_> {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        Block::new().style(THEME.root).render(area, buf);
+        let area = layout(area, Direction::Vertical, vec![1, 0, 1]);
+        self.render_title_bar(area[0], buf);
+        self.render_selected_tab(area[1], buf);
+        self.render_bottom_bar(area[2], buf);
+    }
+}
+
+impl Root<'_> {
+    fn render_title_bar(&self, area: Rect, buf: &mut Buffer) {
+        let area = layout(area, Direction::Horizontal, vec![0, 45]);
+
+        Paragraph::new(Span::styled("Ratatui", THEME.app_title)).render(area[0], buf);
+        let titles = vec!["", " Recipe ", " Email ", " Traceroute ", " Weather "];
+        Tabs::new(titles)
+            .style(THEME.tabs)
+            .highlight_style(THEME.tabs_selected)
+            .select(self.context.tab_index)
+            .divider("")
+            .render(area[1], buf);
+    }
+
+    fn render_selected_tab(&self, area: Rect, buf: &mut Buffer) {
+        let row_index = self.context.row_index;
+        match self.context.tab_index {
+            0 => AboutTab::new(row_index).render(area, buf),
+            1 => RecipeTab::new(row_index).render(area, buf),
+            2 => EmailTab::new(row_index).render(area, buf),
+            3 => TracerouteTab::new(row_index).render(area, buf),
+            4 => WeatherTab::new(row_index).render(area, buf),
+            _ => unreachable!(),
+        };
+    }
+
+    fn render_bottom_bar(&self, area: Rect, buf: &mut Buffer) {
+        let keys = [
+            ("Q/Esc", "Quit"),
+            ("Tab", "Next Tab"),
+            ("↑/k", "Up"),
+            ("↓/j", "Down"),
+        ];
+        let spans = keys
+            .iter()
+            .flat_map(|(key, desc)| {
+                let key = Span::styled(format!(" {} ", key), THEME.key_binding.key);
+                let desc = Span::styled(format!(" {} ", desc), THEME.key_binding.description);
+                [key, desc]
+            })
+            .collect_vec();
+        Paragraph::new(Line::from(spans))
+            .alignment(Alignment::Center)
+            .fg(Color::Indexed(236))
+            .bg(Color::Indexed(232))
+            .render(area, buf);
+    }
+}
+
+/// simple helper method to split an area into multiple sub-areas
+pub fn layout(area: Rect, direction: Direction, heights: Vec<u16>) -> Rc<[Rect]> {
+    let constraints = heights
+        .iter()
+        .map(|&h| {
+            if h > 0 {
+                Constraint::Length(h)
+            } else {
+                Constraint::Min(0)
+            }
+        })
+        .collect_vec();
+    Layout::default()
+        .direction(direction)
+        .constraints(constraints)
+        .split(area)
+}
--- a/examples/demo2/tabs.rs
+++ b/examples/demo2/tabs.rs
@@ -0,0 +1,11 @@
+mod about;
+mod email;
+mod recipe;
+mod traceroute;
+mod weather;
+
+pub use about::AboutTab;
+pub use email::EmailTab;
+pub use recipe::RecipeTab;
+pub use traceroute::TracerouteTab;
+pub use weather::WeatherTab;
--- a/examples/demo2/tabs/about.rs
+++ b/examples/demo2/tabs/about.rs
@@ -0,0 +1,157 @@
+use itertools::Itertools;
+use ratatui::{prelude::*, widgets::*};
+
+use crate::{layout, RgbSwatch, THEME};
+
+const RATATUI_LOGO: [&str; 32] = [
+    "               ███              ",
+    "             ██████             ",
+    "            ███████             ",
+    "           ████████             ",
+    "          █████████             ",
+    "         ██████████             ",
+    "        ████████████            ",
+    "        █████████████           ",
+    "        █████████████     ██████",
+    "         ███████████    ████████",
+    "              █████ ███████████ ",
+    "               ███ ██ee████████ ",
+    "                █ █████████████ ",
+    "            ████ █████████████  ",
+    "           █████████████████    ",
+    "           ████████████████     ",
+    "           ████████████████     ",
+    "            ███ ██████████      ",
+    "          ██    █████████       ",
+    "         █xx█   █████████       ",
+    "        █xxxx█ ██████████       ",
+    "       █xx█xxx█ █████████       ",
+    "      █xx██xxxx█ ████████       ",
+    "     █xxxxxxxxxx█ ██████████    ",
+    "    █xxxxxxxxxxxx█ ██████████   ",
+    "   █xxxxxxx██xxxxx█ █████████   ",
+    "  █xxxxxxxxx██xxxxx█ ████  ███  ",
+    " █xxxxxxxxxxxxxxxxxx█ ██   ███  ",
+    "█xxxxxxxxxxxxxxxxxxxx█ █   ███  ",
+    "█xxxxxxxxxxxxxxxxxxxxx█   ███   ",
+    " █xxxxxxxxxxxxxxxxxxxxx█ ███    ",
+    "  █xxxxxxxxxxxxxxxxxxxxx█ █     ",
+];
+
+pub struct AboutTab {
+    selected_row: usize,
+}
+
+impl AboutTab {
+    pub fn new(selected_row: usize) -> Self {
+        Self { selected_row }
+    }
+}
+
+impl Widget for AboutTab {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        RgbSwatch.render(area, buf);
+        let area = layout(area, Direction::Horizontal, vec![34, 0]);
+        render_crate_description(area[1], buf);
+        render_logo(self.selected_row, area[0], buf);
+    }
+}
+
+fn render_crate_description(area: Rect, buf: &mut Buffer) {
+    let area = area.inner(
+        &(Margin {
+            vertical: 4,
+            horizontal: 2,
+        }),
+    );
+    Clear.render(area, buf); // clear out the color swatches
+    Block::new().style(THEME.content).render(area, buf);
+    let area = area.inner(
+        &(Margin {
+            vertical: 1,
+            horizontal: 2,
+        }),
+    );
+    let text = "- cooking up terminal user interfaces -
+
+    Ratatui is a Rust crate that provides widgets (e.g. Paragraph, Table) and draws them to the \
+    screen efficiently every frame.";
+    Paragraph::new(text)
+        .style(THEME.description)
+        .block(
+            Block::new()
+                .title(" Ratatui ")
+                .title_alignment(Alignment::Center)
+                .borders(Borders::TOP)
+                .border_style(THEME.description_title)
+                .padding(Padding::new(0, 0, 0, 0)),
+        )
+        .wrap(Wrap { trim: true })
+        .scroll((0, 0))
+        .render(area, buf);
+}
+
+/// Use half block characters to render a logo based on the RATATUI_LOGO const.
+///
+/// The logo is rendered in three colors, one for the rat, one for the terminal, and one for the
+/// rat's eye. The eye color alternates between two colors based on the selected row.
+pub fn render_logo(selected_row: usize, area: Rect, buf: &mut Buffer) {
+    let eye_color = if selected_row % 2 == 0 {
+        THEME.logo.rat_eye
+    } else {
+        THEME.logo.rat_eye_alt
+    };
+    let area = area.inner(&Margin {
+        vertical: 0,
+        horizontal: 2,
+    });
+    for (y, (line1, line2)) in RATATUI_LOGO.iter().tuples().enumerate() {
+        for (x, (ch1, ch2)) in line1.chars().zip(line2.chars()).enumerate() {
+            let x = area.left() + x as u16;
+            let y = area.top() + y as u16;
+            let cell = buf.get_mut(x, y);
+            let rat_color = THEME.logo.rat;
+            let term_color = THEME.logo.term;
+            match (ch1, ch2) {
+                ('█', '█') => {
+                    cell.set_char('█');
+                    cell.fg = rat_color;
+                }
+                ('█', ' ') => {
+                    cell.set_char('▀');
+                    cell.fg = rat_color;
+                }
+                (' ', '█') => {
+                    cell.set_char('▄');
+                    cell.fg = rat_color;
+                }
+                ('█', 'x') => {
+                    cell.set_char('▀');
+                    cell.fg = rat_color;
+                    cell.bg = term_color;
+                }
+                ('x', '█') => {
+                    cell.set_char('▄');
+                    cell.fg = rat_color;
+                    cell.bg = term_color;
+                }
+                ('x', 'x') => {
+                    cell.set_char(' ');
+                    cell.fg = term_color;
+                    cell.bg = term_color;
+                }
+                ('█', 'e') => {
+                    cell.set_char('▀');
+                    cell.fg = rat_color;
+                    cell.bg = eye_color;
+                }
+                ('e', '█') => {
+                    cell.set_char('▄');
+                    cell.fg = rat_color;
+                    cell.bg = eye_color;
+                }
+                (_, _) => {}
+            };
+        }
+    }
+}
--- a/examples/demo2/tabs/email.rs
+++ b/examples/demo2/tabs/email.rs
@@ -0,0 +1,143 @@
+use itertools::Itertools;
+use ratatui::{prelude::*, widgets::*};
+use unicode_width::UnicodeWidthStr;
+
+use crate::{layout, RgbSwatch, THEME};
+
+#[derive(Debug, Default)]
+pub struct Email {
+    from: &'static str,
+    subject: &'static str,
+    body: &'static str,
+}
+
+const EMAILS: &[Email] = &[
+    Email {
+        from: "Alice <alice@example.com>",
+        subject: "Hello",
+        body: "Hi Bob,\nHow are you?\n\nAlice",
+    },
+    Email {
+        from: "Bob <bob@example.com>",
+        subject: "Re: Hello",
+        body: "Hi Alice,\nI'm fine, thanks!\n\nBob",
+    },
+    Email {
+        from: "Charlie <charlie@example.com>",
+        subject: "Re: Hello",
+        body: "Hi Alice,\nI'm fine, thanks!\n\nCharlie",
+    },
+    Email {
+        from: "Dave <dave@example.com>",
+        subject: "Re: Hello (STOP REPLYING TO ALL)",
+        body: "Hi Everyone,\nPlease stop replying to all.\n\nDave",
+    },
+    Email {
+        from: "Eve <eve@example.com>",
+        subject: "Re: Hello (STOP REPLYING TO ALL)",
+        body: "Hi Everyone,\nI'm reading all your emails.\n\nEve",
+    },
+];
+
+#[derive(Debug, Default)]
+pub struct EmailTab {
+    selected_index: usize,
+}
+
+impl EmailTab {
+    pub fn new(selected_index: usize) -> Self {
+        Self {
+            selected_index: selected_index % EMAILS.len(),
+        }
+    }
+}
+
+impl Widget for EmailTab {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        RgbSwatch.render(area, buf);
+        let area = area.inner(&Margin {
+            vertical: 1,
+            horizontal: 2,
+        });
+        Clear.render(area, buf);
+        let area = layout(area, Direction::Vertical, vec![5, 0]);
+        render_inbox(self.selected_index, area[0], buf);
+        render_email(self.selected_index, area[1], buf);
+    }
+}
+fn render_inbox(selected_index: usize, area: Rect, buf: &mut Buffer) {
+    let area = layout(area, Direction::Vertical, vec![1, 0]);
+    let theme = THEME.email;
+    Tabs::new(vec![" Inbox ", " Sent ", " Drafts "])
+        .style(theme.tabs)
+        .highlight_style(theme.tabs_selected)
+        .select(0)
+        .divider("")
+        .render(area[0], buf);
+
+    let highlight_symbol = ">>";
+    let from_width = EMAILS
+        .iter()
+        .map(|e| e.from.width())
+        .max()
+        .unwrap_or_default();
+    let items = EMAILS
+        .iter()
+        .map(|e| {
+            let from = format!("{:width$}", e.from, width = from_width).into();
+            ListItem::new(Line::from(vec![from, " ".into(), e.subject.into()]))
+        })
+        .collect_vec();
+    let mut state = ListState::default().with_selected(Some(selected_index));
+    StatefulWidget::render(
+        List::new(items)
+            .style(theme.inbox)
+            .highlight_style(theme.selected_item)
+            .highlight_symbol(highlight_symbol),
+        area[1],
+        buf,
+        &mut state,
+    );
+    let mut scrollbar_state = ScrollbarState::default()
+        .content_length(EMAILS.len())
+        .position(selected_index);
+    Scrollbar::default()
+        .begin_symbol(None)
+        .end_symbol(None)
+        .track_symbol(None)
+        .thumb_symbol("▐")
+        .render(area[1], buf, &mut scrollbar_state);
+}
+
+fn render_email(selected_index: usize, area: Rect, buf: &mut Buffer) {
+    let theme = THEME.email;
+    let email = EMAILS.get(selected_index);
+    let block = Block::new()
+        .style(theme.body)
+        .padding(Padding::new(2, 2, 0, 0))
+        .borders(Borders::TOP)
+        .border_type(BorderType::Thick);
+    let inner = block.inner(area);
+    block.render(area, buf);
+    if let Some(email) = email {
+        let area = layout(inner, Direction::Vertical, vec![3, 0]);
+        let headers = vec![
+            Line::from(vec![
+                "From: ".set_style(theme.header),
+                email.from.set_style(theme.header_value),
+            ]),
+            Line::from(vec![
+                "Subject: ".set_style(theme.header),
+                email.subject.set_style(theme.header_value),
+            ]),
+            "-".repeat(inner.width as usize).dim().into(),
+        ];
+        Paragraph::new(headers)
+            .style(theme.body)
+            .render(area[0], buf);
+        let body = email.body.lines().map(Line::from).collect_vec();
+        Paragraph::new(body).style(theme.body).render(area[1], buf);
+    } else {
+        Paragraph::new("No email selected").render(inner, buf);
+    }
+}
--- a/examples/demo2/tabs/recipe.rs
+++ b/examples/demo2/tabs/recipe.rs
@@ -0,0 +1,171 @@
+use itertools::Itertools;
+use ratatui::{prelude::*, widgets::*};
+
+use crate::{layout, RgbSwatch, THEME};
+
+#[derive(Debug, Default, Clone, Copy)]
+struct Ingredient {
+    quantity: &'static str,
+    name: &'static str,
+}
+
+impl Ingredient {
+    fn height(&self) -> u16 {
+        self.name.lines().count() as u16
+    }
+}
+
+impl<'a> From<Ingredient> for Row<'a> {
+    fn from(i: Ingredient) -> Self {
+        Row::new(vec![i.quantity, i.name]).height(i.height())
+    }
+}
+
+// https://www.realsimple.com/food-recipes/browse-all-recipes/ratatouille
+const RECIPE: &[(&str, &str)] = &[
+    (
+        "Step 1: ",
+        "Over medium-low heat, add the oil to a large skillet with the onion, garlic, and bay \
+        leaf, stirring occasionally, until the onion has softened.",
+    ),
+    (
+        "Step 2: ",
+        "Add the eggplant and cook, stirring occasionally, for 8 minutes or until the eggplant \
+        has softened. Stir in the zucchini, red bell pepper, tomatoes, and salt, and cook over \
+        medium heat, stirring occasionally, for 5 to 7 minutes or until the vegetables are \
+        tender. Stir in the basil and few grinds of pepper to taste.",
+    ),
+];
+
+const INGREDIENTS: &[Ingredient] = &[
+    Ingredient {
+        quantity: "4 tbsp",
+        name: "olive oil",
+    },
+    Ingredient {
+        quantity: "1",
+        name: "onion thinly sliced",
+    },
+    Ingredient {
+        quantity: "4",
+        name: "cloves garlic\npeeled and sliced",
+    },
+    Ingredient {
+        quantity: "1",
+        name: "small bay leaf",
+    },
+    Ingredient {
+        quantity: "1",
+        name: "small eggplant cut\ninto 1/2 inch cubes",
+    },
+    Ingredient {
+        quantity: "1",
+        name: "small zucchini halved\nlengthwise and cut\ninto thin slices",
+    },
+    Ingredient {
+        quantity: "1",
+        name: "red bell pepper cut\ninto slivers",
+    },
+    Ingredient {
+        quantity: "4",
+        name: "plum tomatoes\ncoarsely chopped",
+    },
+    Ingredient {
+        quantity: "1 tsp",
+        name: "kosher salt",
+    },
+    Ingredient {
+        quantity: "1/4 cup",
+        name: "shredded fresh basil\nleaves",
+    },
+    Ingredient {
+        quantity: "",
+        name: "freshly ground black\npepper",
+    },
+];
+
+#[derive(Debug)]
+pub struct RecipeTab {
+    selected_row: usize,
+}
+
+impl RecipeTab {
+    pub fn new(selected_row: usize) -> Self {
+        Self {
+            selected_row: selected_row % INGREDIENTS.len(),
+        }
+    }
+}
+
+impl Widget for RecipeTab {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        RgbSwatch.render(area, buf);
+        let area = area.inner(&Margin {
+            vertical: 1,
+            horizontal: 2,
+        });
+        Clear.render(area, buf);
+        Block::new()
+            .title("Ratatouille Recipe".bold().white())
+            .title_alignment(Alignment::Center)
+            .style(THEME.content)
+            .padding(Padding::new(1, 1, 2, 1))
+            .render(area, buf);
+
+        let scrollbar_area = Rect {
+            y: area.y + 2,
+            height: area.height - 3,
+            ..area
+        };
+        render_scrollbar(self.selected_row, scrollbar_area, buf);
+
+        let area = area.inner(&Margin {
+            horizontal: 2,
+            vertical: 1,
+        });
+        let area = layout(area, Direction::Horizontal, vec![44, 0]);
+
+        render_recipe(area[0], buf);
+        render_ingredients(self.selected_row, area[1], buf);
+    }
+}
+
+fn render_recipe(area: Rect, buf: &mut Buffer) {
+    let lines = RECIPE
+        .iter()
+        .map(|(step, text)| Line::from(vec![step.white().bold(), text.gray()]))
+        .collect_vec();
+    Paragraph::new(lines)
+        .wrap(Wrap { trim: true })
+        .block(Block::new().padding(Padding::new(0, 1, 0, 0)))
+        .render(area, buf);
+}
+
+fn render_ingredients(selected_row: usize, area: Rect, buf: &mut Buffer) {
+    let mut state = TableState::default().with_selected(Some(selected_row));
+    let rows = INGREDIENTS.iter().map(|&i| i.into()).collect_vec();
+    let theme = THEME.recipe;
+    StatefulWidget::render(
+        Table::new(rows)
+            .block(Block::new().style(theme.ingredients))
+            .header(Row::new(vec!["Qty", "Ingredient"]).style(theme.ingredients_header))
+            .widths(&[Constraint::Length(7), Constraint::Length(30)])
+            .highlight_style(Style::new().light_yellow()),
+        area,
+        buf,
+        &mut state,
+    );
+}
+
+fn render_scrollbar(position: usize, area: Rect, buf: &mut Buffer) {
+    let mut state = ScrollbarState::default()
+        .content_length(INGREDIENTS.len())
+        .viewport_content_length(6)
+        .position(position);
+    Scrollbar::new(ScrollbarOrientation::VerticalRight)
+        .begin_symbol(None)
+        .end_symbol(None)
+        .track_symbol(None)
+        .thumb_symbol("▐")
+        .render(area, buf, &mut state)
+}
--- a/examples/demo2/tabs/traceroute.rs
+++ b/examples/demo2/tabs/traceroute.rs
@@ -0,0 +1,199 @@
+use itertools::Itertools;
+use ratatui::{
+    prelude::*,
+    widgets::{canvas::*, *},
+};
+
+use crate::{layout, RgbSwatch, THEME};
+
+#[derive(Debug)]
+pub struct TracerouteTab {
+    selected_row: usize,
+}
+
+impl TracerouteTab {
+    pub fn new(selected_row: usize) -> Self {
+        Self {
+            selected_row: selected_row % HOPS.len(),
+        }
+    }
+}
+
+impl Widget for TracerouteTab {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        RgbSwatch.render(area, buf);
+        let area = area.inner(&Margin {
+            vertical: 1,
+            horizontal: 2,
+        });
+        Clear.render(area, buf);
+        Block::new().style(THEME.content).render(area, buf);
+        let area = Layout::default()
+            .direction(Direction::Horizontal)
+            .constraints([Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)])
+            .split(area);
+        let left_area = layout(area[0], Direction::Vertical, vec![0, 3]);
+        render_hops(self.selected_row, left_area[0], buf);
+        render_ping(self.selected_row, left_area[1], buf);
+        render_map(self.selected_row, area[1], buf);
+    }
+}
+
+fn render_hops(selected_row: usize, area: Rect, buf: &mut Buffer) {
+    let mut state = TableState::default().with_selected(Some(selected_row));
+    let rows = HOPS
+        .iter()
+        .map(|hop| Row::new(vec![hop.host, hop.address]))
+        .collect_vec();
+    let block = Block::default()
+        .title("Traceroute bad.horse".bold().white())
+        .title_alignment(Alignment::Center)
+        .padding(Padding::new(1, 1, 1, 1));
+    StatefulWidget::render(
+        Table::new(rows)
+            .header(Row::new(vec!["Host", "Address"]).set_style(THEME.traceroute.header))
+            .widths(&[Constraint::Max(100), Constraint::Length(15)])
+            .highlight_style(THEME.traceroute.selected)
+            .block(block),
+        area,
+        buf,
+        &mut state,
+    );
+    let mut scrollbar_state = ScrollbarState::default()
+        .content_length(HOPS.len())
+        .position(selected_row);
+    let area = Rect {
+        width: area.width + 1,
+        y: area.y + 3,
+        height: area.height - 4,
+        ..area
+    };
+    Scrollbar::default()
+        .orientation(ScrollbarOrientation::VerticalLeft)
+        .begin_symbol(None)
+        .end_symbol(None)
+        .track_symbol(None)
+        .thumb_symbol("▌")
+        .render(area, buf, &mut scrollbar_state);
+}
+
+pub fn render_ping(progress: usize, area: Rect, buf: &mut Buffer) {
+    let mut data = [
+        8, 8, 8, 8, 7, 7, 7, 6, 6, 5, 4, 3, 3, 2, 2, 1, 1, 1, 2, 2, 3, 4, 5, 6, 7, 7, 8, 8, 8, 7,
+        7, 6, 5, 4, 3, 2, 1, 1, 1, 1, 1, 2, 4, 6, 7, 8, 8, 8, 8, 6, 4, 2, 1, 1, 1, 1, 2, 2, 2, 3,
+        3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 6, 6, 6, 6, 7, 7, 7,
+    ];
+    let mid = progress % data.len();
+    data.rotate_left(mid);
+    Sparkline::default()
+        .block(
+            Block::new()
+                .title("Ping")
+                .title_alignment(Alignment::Center)
+                .border_type(BorderType::Thick),
+        )
+        .data(&data)
+        .style(THEME.traceroute.ping)
+        .render(area, buf);
+}
+
+fn render_map(selected_row: usize, area: Rect, buf: &mut Buffer) {
+    let theme = THEME.traceroute.map;
+    let path: Option<(&Hop, &Hop)> = HOPS.iter().tuple_windows().nth(selected_row);
+    let map = Map {
+        resolution: canvas::MapResolution::High,
+        color: theme.color,
+    };
+    Canvas::default()
+        .background_color(theme.background_color)
+        .block(
+            Block::new()
+                .padding(Padding::new(1, 0, 1, 0))
+                .style(theme.style),
+        )
+        .marker(Marker::HalfBlock)
+        // picked to show Australia for the demo as it's the most interesting part of the map
+        // (and the only part with hops ;))
+        .x_bounds([112.0, 155.0])
+        .y_bounds([-46.0, -11.0])
+        .paint(|context| {
+            context.draw(&map);
+            if let Some(path) = path {
+                context.draw(&canvas::Line::new(
+                    path.0.location.0,
+                    path.0.location.1,
+                    path.1.location.0,
+                    path.1.location.1,
+                    theme.path,
+                ));
+                context.draw(&Points {
+                    color: theme.source,
+                    coords: &[path.0.location], // sydney
+                });
+                context.draw(&Points {
+                    color: theme.destination,
+                    coords: &[path.1.location], // perth
+                });
+            }
+        })
+        .render(area, buf);
+}
+
+#[derive(Debug)]
+struct Hop {
+    host: &'static str,
+    address: &'static str,
+    location: (f64, f64),
+}
+
+impl Hop {
+    const fn new(name: &'static str, address: &'static str, location: (f64, f64)) -> Self {
+        Self {
+            host: name,
+            address,
+            location,
+        }
+    }
+}
+
+const CANBERRA: (f64, f64) = (149.1, -35.3);
+const SYDNEY: (f64, f64) = (151.1, -33.9);
+const MELBOURNE: (f64, f64) = (144.9, -37.8);
+const PERTH: (f64, f64) = (115.9, -31.9);
+const DARWIN: (f64, f64) = (130.8, -12.4);
+const BRISBANE: (f64, f64) = (153.0, -27.5);
+const ADELAIDE: (f64, f64) = (138.6, -34.9);
+
+// Go traceroute bad.horse some time, it's fun. these locations are made up and don't correspond
+// to the actual IP addresses (which are in Toronto, Canada).
+const HOPS: &[Hop] = &[
+    Hop::new("home", "127.0.0.1", CANBERRA),
+    Hop::new("bad.horse", "162.252.205.130", SYDNEY),
+    Hop::new("bad.horse", "162.252.205.131", MELBOURNE),
+    Hop::new("bad.horse", "162.252.205.132", BRISBANE),
+    Hop::new("bad.horse", "162.252.205.133", SYDNEY),
+    Hop::new("he.rides.across.the.nation", "162.252.205.134", PERTH),
+    Hop::new("the.thoroughbred.of.sin", "162.252.205.135", DARWIN),
+    Hop::new("he.got.the.application", "162.252.205.136", BRISBANE),
+    Hop::new("that.you.just.sent.in", "162.252.205.137", ADELAIDE),
+    Hop::new("it.needs.evaluation", "162.252.205.138", DARWIN),
+    Hop::new("so.let.the.games.begin", "162.252.205.139", PERTH),
+    Hop::new("a.heinous.crime", "162.252.205.140", BRISBANE),
+    Hop::new("a.show.of.force", "162.252.205.141", CANBERRA),
+    Hop::new("a.murder.would.be.nice.of.course", "162.252.205.142", PERTH),
+    Hop::new("bad.horse", "162.252.205.143", MELBOURNE),
+    Hop::new("bad.horse", "162.252.205.144", DARWIN),
+    Hop::new("bad.horse", "162.252.205.145", MELBOURNE),
+    Hop::new("he-s.bad", "162.252.205.146", PERTH),
+    Hop::new("the.evil.league.of.evil", "162.252.205.147", BRISBANE),
+    Hop::new("is.watching.so.beware", "162.252.205.148", DARWIN),
+    Hop::new("the.grade.that.you.receive", "162.252.205.149", PERTH),
+    Hop::new("will.be.your.last.we.swear", "162.252.205.150", ADELAIDE),
+    Hop::new("so.make.the.bad.horse.gleeful", "162.252.205.151", SYDNEY),
+    Hop::new("or.he-ll.make.you.his.mare", "162.252.205.152", MELBOURNE),
+    Hop::new("o_o", "162.252.205.153", BRISBANE),
+    Hop::new("you-re.saddled.up", "162.252.205.154", DARWIN),
+    Hop::new("there-s.no.recourse", "162.252.205.155", PERTH),
+    Hop::new("it-s.hi-ho.silver", "162.252.205.156", SYDNEY),
+    Hop::new("signed.bad.horse", "162.252.205.157", CANBERRA),
+];
--- a/examples/demo2/tabs/weather.rs
+++ b/examples/demo2/tabs/weather.rs
@@ -0,0 +1,141 @@
+use itertools::Itertools;
+use palette::Okhsv;
+use ratatui::{
+    prelude::*,
+    widgets::{calendar::CalendarEventStore, *},
+};
+use time::OffsetDateTime;
+
+use crate::{color_from_oklab, layout, RgbSwatch, THEME};
+
+pub struct WeatherTab {
+    pub selected_row: usize,
+}
+
+impl WeatherTab {
+    pub fn new(selected_row: usize) -> Self {
+        Self { selected_row }
+    }
+}
+
+impl Widget for WeatherTab {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        RgbSwatch.render(area, buf);
+        let area = area.inner(&Margin {
+            vertical: 1,
+            horizontal: 2,
+        });
+        Clear.render(area, buf);
+        Block::new().style(THEME.content).render(area, buf);
+
+        let area = area.inner(&Margin {
+            horizontal: 2,
+            vertical: 1,
+        });
+        let area = layout(area, Direction::Vertical, vec![0, 1, 1]);
+        render_gauges(self.selected_row, area[2], buf);
+
+        let area = layout(area[0], Direction::Horizontal, vec![23, 0]);
+        render_calendar(area[0], buf);
+        let area = layout(area[1], Direction::Horizontal, vec![29, 0]);
+        render_simple_barchart(area[0], buf);
+        render_horizontal_barchart(area[1], buf);
+    }
+}
+
+fn render_calendar(area: Rect, buf: &mut Buffer) {
+    let date = OffsetDateTime::now_utc().date();
+    calendar::Monthly::new(date, CalendarEventStore::today(Style::new().red().bold()))
+        .block(Block::new().padding(Padding::new(0, 0, 2, 0)))
+        .show_month_header(Style::new().bold())
+        .show_weekdays_header(Style::new().italic())
+        .render(area, buf);
+}
+
+fn render_simple_barchart(area: Rect, buf: &mut Buffer) {
+    let data = [
+        ("Sat", 76),
+        ("Sun", 69),
+        ("Mon", 65),
+        ("Tue", 67),
+        ("Wed", 65),
+        ("Thu", 69),
+        ("Fri", 73),
+    ];
+    let data = data
+        .into_iter()
+        .map(|(label, value)| {
+            Bar::default()
+                .value(value)
+                // This doesn't actually render correctly as the text is too wide for the bar
+                // See https://github.com/ratatui-org/ratatui/issues/513 for more info
+                // (the demo GIFs hack around this by hacking the calculation in bars.rs)
+                .text_value(format!("{}°", value))
+                .style(if value > 70 {
+                    Style::new().fg(Color::Red)
+                } else {
+                    Style::new().fg(Color::Yellow)
+                })
+                .value_style(if value > 70 {
+                    Style::new().fg(Color::Gray).bg(Color::Red).bold()
+                } else {
+                    Style::new().fg(Color::DarkGray).bg(Color::Yellow).bold()
+                })
+                .label(label.into())
+        })
+        .collect_vec();
+    let group = BarGroup::default().bars(&data);
+    BarChart::default()
+        .data(group)
+        .bar_width(3)
+        .bar_gap(1)
+        .render(area, buf);
+}
+
+fn render_horizontal_barchart(area: Rect, buf: &mut Buffer) {
+    let bg = Color::Rgb(32, 48, 96);
+    let data = [
+        Bar::default().text_value("Winter 37-51".into()).value(51),
+        Bar::default().text_value("Spring 40-65".into()).value(65),
+        Bar::default().text_value("Summer 54-77".into()).value(77),
+        Bar::default()
+            .text_value("Fall 41-71".into())
+            .value(71)
+            .value_style(Style::new().bold()), // current season
+    ];
+    let group = BarGroup::default().label("GPU".into()).bars(&data);
+    BarChart::default()
+        .block(Block::new().padding(Padding::new(0, 0, 2, 0)))
+        .direction(Direction::Horizontal)
+        .data(group)
+        .bar_gap(1)
+        .bar_style(Style::new().fg(bg))
+        .value_style(Style::new().bg(bg).fg(Color::Gray))
+        .render(area, buf);
+}
+
+pub fn render_gauges(progress: usize, area: Rect, buf: &mut Buffer) {
+    let percent = (progress * 3).min(100) as f64;
+
+    render_line_gauge(percent, area, buf);
+}
+
+fn render_line_gauge(percent: f64, area: Rect, buf: &mut Buffer) {
+    // cycle color hue based on the percent for a neat effect yellow -> red
+    let hue = 90.0 - (percent as f32 * 0.6);
+    let value = Okhsv::max_value();
+    let fg = color_from_oklab(hue, Okhsv::max_saturation(), value);
+    let bg = color_from_oklab(hue, Okhsv::max_saturation(), value * 0.5);
+    let label = if percent < 100.0 {
+        format!("Downloading: {}%", percent)
+    } else {
+        "Download Complete!".into()
+    };
+    LineGauge::default()
+        .ratio(percent / 100.0)
+        .label(label)
+        .style(Style::new().light_blue())
+        .gauge_style(Style::new().fg(fg).bg(bg))
+        .line_set(symbols::line::THICK)
+        .render(area, buf);
+}
--- a/examples/demo2/term.rs
+++ b/examples/demo2/term.rs
@@ -0,0 +1,71 @@
+use std::{
+    io::{self, stdout, Stdout},
+    ops::{Deref, DerefMut},
+    time::Duration,
+};
+
+use anyhow::{Context, Result};
+use crossterm::{
+    event::{self, Event},
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    ExecutableCommand,
+};
+use ratatui::prelude::*;
+
+/// A wrapper around the terminal that handles setting up and tearing down the terminal
+/// and provides a helper method to read events from the terminal.
+#[derive(Debug)]
+pub struct Term {
+    terminal: Terminal<CrosstermBackend<Stdout>>,
+}
+
+impl Term {
+    pub fn start() -> Result<Self> {
+        // this size is to match the size of the terminal when running the demo
+        // using vhs in a 1280x640 sized window (github social preview size)
+        let options = TerminalOptions {
+            viewport: Viewport::Fixed(Rect::new(0, 0, 81, 18)),
+        };
+        let terminal = Terminal::with_options(CrosstermBackend::new(io::stdout()), options)?;
+        enable_raw_mode().context("enable raw mode")?;
+        stdout()
+            .execute(EnterAlternateScreen)
+            .context("enter alternate screen")?;
+        Ok(Self { terminal })
+    }
+
+    pub fn stop() -> Result<()> {
+        disable_raw_mode().context("disable raw mode")?;
+        stdout()
+            .execute(LeaveAlternateScreen)
+            .context("leave alternate screen")?;
+        Ok(())
+    }
+
+    pub fn next_event(timeout: Duration) -> io::Result<Option<Event>> {
+        if !event::poll(timeout)? {
+            return Ok(None);
+        }
+        let event = event::read()?;
+        Ok(Some(event))
+    }
+}
+
+impl Deref for Term {
+    type Target = Terminal<CrosstermBackend<Stdout>>;
+    fn deref(&self) -> &Self::Target {
+        &self.terminal
+    }
+}
+
+impl DerefMut for Term {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.terminal
+    }
+}
+
+impl Drop for Term {
+    fn drop(&mut self) {
+        let _ = Term::stop();
+    }
+}
--- a/examples/demo2/theme.rs
+++ b/examples/demo2/theme.rs
@@ -0,0 +1,136 @@
+use ratatui::prelude::*;
+
+pub struct Theme {
+    pub root: Style,
+    pub content: Style,
+    pub app_title: Style,
+    pub tabs: Style,
+    pub tabs_selected: Style,
+    pub borders: Style,
+    pub description: Style,
+    pub description_title: Style,
+    pub key_binding: KeyBinding,
+    pub logo: Logo,
+    pub email: Email,
+    pub traceroute: Traceroute,
+    pub recipe: Recipe,
+}
+
+pub struct KeyBinding {
+    pub key: Style,
+    pub description: Style,
+}
+
+pub struct Logo {
+    pub rat: Color,
+    pub rat_eye: Color,
+    pub rat_eye_alt: Color,
+    pub term: Color,
+}
+
+pub struct Email {
+    pub tabs: Style,
+    pub tabs_selected: Style,
+    pub inbox: Style,
+    pub item: Style,
+    pub selected_item: Style,
+    pub header: Style,
+    pub header_value: Style,
+    pub body: Style,
+}
+
+pub struct Traceroute {
+    pub header: Style,
+    pub selected: Style,
+    pub ping: Style,
+    pub map: Map,
+}
+
+pub struct Map {
+    pub style: Style,
+    pub color: Color,
+    pub path: Color,
+    pub source: Color,
+    pub destination: Color,
+    pub background_color: Color,
+}
+
+pub struct Recipe {
+    pub ingredients: Style,
+    pub ingredients_header: Style,
+}
+
+pub const THEME: Theme = Theme {
+    root: Style::new().bg(DARK_BLUE),
+    content: Style::new().bg(DARK_BLUE).fg(LIGHT_GRAY),
+    app_title: Style::new()
+        .fg(WHITE)
+        .bg(DARK_BLUE)
+        .add_modifier(Modifier::BOLD),
+    tabs: Style::new().fg(MID_GRAY).bg(DARK_BLUE),
+    tabs_selected: Style::new()
+        .fg(WHITE)
+        .bg(DARK_BLUE)
+        .add_modifier(Modifier::BOLD)
+        .add_modifier(Modifier::REVERSED),
+    borders: Style::new().fg(LIGHT_GRAY),
+    description: Style::new().fg(LIGHT_GRAY).bg(DARK_BLUE),
+    description_title: Style::new().fg(LIGHT_GRAY).add_modifier(Modifier::BOLD),
+    logo: Logo {
+        rat: WHITE,
+        rat_eye: BLACK,
+        rat_eye_alt: RED,
+        term: BLACK,
+    },
+    key_binding: KeyBinding {
+        key: Style::new().fg(BLACK).bg(DARK_GRAY),
+        description: Style::new().fg(DARK_GRAY).bg(BLACK),
+    },
+    email: Email {
+        tabs: Style::new().fg(MID_GRAY).bg(DARK_BLUE),
+        tabs_selected: Style::new()
+            .fg(WHITE)
+            .bg(DARK_BLUE)
+            .add_modifier(Modifier::BOLD),
+        inbox: Style::new().bg(DARK_BLUE).fg(LIGHT_GRAY),
+        item: Style::new().fg(LIGHT_GRAY),
+        selected_item: Style::new().fg(LIGHT_YELLOW),
+        header: Style::new().add_modifier(Modifier::BOLD),
+        header_value: Style::new().fg(LIGHT_GRAY),
+        body: Style::new().bg(DARK_BLUE).fg(LIGHT_GRAY),
+    },
+    traceroute: Traceroute {
+        header: Style::new()
+            .bg(DARK_BLUE)
+            .add_modifier(Modifier::BOLD)
+            .add_modifier(Modifier::UNDERLINED),
+        selected: Style::new().fg(LIGHT_YELLOW),
+        ping: Style::new().fg(WHITE),
+        map: Map {
+            style: Style::new().bg(DARK_BLUE),
+            background_color: DARK_BLUE,
+            color: LIGHT_GRAY,
+            path: LIGHT_BLUE,
+            source: LIGHT_GREEN,
+            destination: LIGHT_RED,
+        },
+    },
+    recipe: Recipe {
+        ingredients: Style::new().bg(DARK_BLUE).fg(LIGHT_GRAY),
+        ingredients_header: Style::new()
+            .add_modifier(Modifier::BOLD)
+            .add_modifier(Modifier::UNDERLINED),
+    },
+};
+
+const DARK_BLUE: Color = Color::Rgb(16, 24, 48);
+const LIGHT_BLUE: Color = Color::Rgb(64, 96, 192);
+const LIGHT_YELLOW: Color = Color::Rgb(192, 192, 96);
+const LIGHT_GREEN: Color = Color::Rgb(64, 192, 96);
+const LIGHT_RED: Color = Color::Rgb(192, 96, 96);
+const RED: Color = Color::Indexed(160);
+const BLACK: Color = Color::Indexed(232); // not really black, often #080808
+const DARK_GRAY: Color = Color::Indexed(238);
+const MID_GRAY: Color = Color::Indexed(244);
+const LIGHT_GRAY: Color = Color::Indexed(250);
+const WHITE: Color = Color::Indexed(255); // not really white, often #eeeeee
--- a/examples/docsrs.rs
+++ b/examples/docsrs.rs
@@ -0,0 +1,126 @@
+use std::io::{self, stdout};
+
+use crossterm::{
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    ExecutableCommand,
+};
+use ratatui::{prelude::*, widgets::*};
+
+/// Example code for libr.rs
+///
+/// When cargo-rdme supports doc comments that import from code, this will be imported
+/// rather than copied to the lib.rs file.
+fn main() -> io::Result<()> {
+    let arg = std::env::args().nth(1).unwrap_or_default();
+    enable_raw_mode()?;
+    stdout().execute(EnterAlternateScreen)?;
+    let mut terminal = Terminal::new(CrosstermBackend::new(stdout()))?;
+
+    let mut should_quit = false;
+    while !should_quit {
+        terminal.draw(match arg.as_str() {
+            "hello_world" => hello_world,
+            "layout" => layout,
+            "styling" => styling,
+            _ => hello_world,
+        })?;
+        should_quit = handle_events()?;
+    }
+
+    disable_raw_mode()?;
+    stdout().execute(LeaveAlternateScreen)?;
+    Ok(())
+}
+
+fn hello_world(frame: &mut Frame) {
+    frame.render_widget(
+        Paragraph::new("Hello World!")
+            .block(Block::default().title("Greeting").borders(Borders::ALL)),
+        frame.size(),
+    );
+}
+
+use crossterm::event::{self, Event, KeyCode};
+fn handle_events() -> io::Result<bool> {
+    if event::poll(std::time::Duration::from_millis(50))? {
+        if let Event::Key(key) = event::read()? {
+            if key.kind == event::KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                return Ok(true);
+            }
+        }
+    }
+    Ok(false)
+}
+
+fn layout(frame: &mut Frame) {
+    let main_layout = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(1),
+            Constraint::Min(0),
+            Constraint::Length(1),
+        ])
+        .split(frame.size());
+    frame.render_widget(
+        Block::new().borders(Borders::TOP).title("Title Bar"),
+        main_layout[0],
+    );
+    frame.render_widget(
+        Block::new().borders(Borders::TOP).title("Status Bar"),
+        main_layout[2],
+    );
+
+    let inner_layout = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
+        .split(main_layout[1]);
+    frame.render_widget(
+        Block::default().borders(Borders::ALL).title("Left"),
+        inner_layout[0],
+    );
+    frame.render_widget(
+        Block::default().borders(Borders::ALL).title("Right"),
+        inner_layout[1],
+    );
+}
+
+fn styling(frame: &mut Frame) {
+    let areas = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(1),
+            Constraint::Length(1),
+            Constraint::Length(1),
+            Constraint::Length(1),
+            Constraint::Min(0),
+        ])
+        .split(frame.size());
+
+    let span1 = Span::raw("Hello ");
+    let span2 = Span::styled(
+        "World",
+        Style::new()
+            .fg(Color::Green)
+            .bg(Color::White)
+            .add_modifier(Modifier::BOLD),
+    );
+    let span3 = "!".red().on_light_yellow().italic();
+
+    let line = Line::from(vec![span1, span2, span3]);
+    let text: Text = Text::from(vec![line]);
+
+    frame.render_widget(Paragraph::new(text), areas[0]);
+    // or using the short-hand syntax and implicit conversions
+    frame.render_widget(
+        Paragraph::new("Hello World!".red().on_white().bold()),
+        areas[1],
+    );
+
+    // to style the whole widget instead of just the text
+    frame.render_widget(
+        Paragraph::new("Hello World!").style(Style::new().red().on_white()),
+        areas[2],
+    );
+    // or using the short-hand syntax
+    frame.render_widget(Paragraph::new("Hello World!").blue().on_yellow(), areas[3]);
+}
--- a/examples/docsrs.tape
+++ b/examples/docsrs.tape
@@ -0,0 +1,39 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/demo.tape`
+# NOTE: Requires VHS 0.6.1 or later for Screenshot support
+Output "target/docsrs.gif"
+Set Theme "Aardvark Blue"
+# The reason for this strange size is that the social preview image for this
+# demo is 1280x64 with 80 pixels of padding on each side. We want a version
+# without the padding for README.md, etc.
+Set Width 640
+Set Height 160
+Set Padding 0
+Hide
+Type "cargo run --example docsrs --features crossterm"
+Enter
+Sleep 2s
+Show
+Sleep 1s
+Screenshot "target/docsrs-hello.png"
+Sleep 1s
+Hide
+Type "q"
+Type "cargo run --example docsrs --features crossterm -- layout"
+Enter
+Sleep 2s
+Show
+Sleep 1s
+Screenshot "target/docsrs-layout.png"
+Sleep 1s
+Hide
+Type "q"
+Type "cargo run --example docsrs --features crossterm -- styling"
+Enter
+Sleep 2s
+Show
+Sleep 1s
+Screenshot "target/docsrs-styling.png"
+Sleep 1s
+Hide
+Type "q"
--- a/examples/gauge.rs
+++ b/examples/gauge.rs
@@ -1,158 +1,187 @@
-extern crate termion;
-extern crate tui;
+use std::{
+    io::{self, stdout, Stdout},
+    rc::Rc,
+    time::Duration,
+};

-use std::io;
-use std::sync::mpsc;
-use std::thread;
-use std::time;
+use anyhow::Result;
+use crossterm::{
+    event::{self, Event, KeyCode, KeyEventKind},
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    ExecutableCommand,
+};
+use ratatui::{
+    prelude::*,
+    widgets::{block::Title, *},
+};

-use termion::event;
-use termion::input::TermRead;
-
-use tui::backend::MouseBackend;
-use tui::layout::{Constraint, Direction, Layout, Rect};
-use tui::style::{Color, Modifier, Style};
-use tui::widgets::{Block, Borders, Gauge, Widget};
-use tui::Terminal;
+fn main() -> Result<()> {
+    App::run()
+}

 struct App {
-    size: Rect,
+    term: Term,
+    should_quit: bool,
+    state: AppState,
+}
+
+#[derive(Debug, Default, Clone, Copy)]
+struct AppState {
    progress1: u16,
    progress2: u16,
-    progress3: u16,
+    progress3: f64,
    progress4: u16,
 }

 impl App {
-    fn new() -> App {
-        App {
-            size: Rect::default(),
-            progress1: 0,
-            progress2: 0,
-            progress3: 0,
-            progress4: 0,
+    fn run() -> Result<()> {
+        // run at ~10 fps minus the time it takes to draw
+        let timeout = Duration::from_secs_f32(1.0 / 10.0);
+        let mut app = Self::start()?;
+        while !app.should_quit {
+            app.update();
+            app.draw()?;
+            app.handle_events(timeout)?;
        }
+        app.stop()?;
+        Ok(())
    }

-    fn advance(&mut self) {
-        self.progress1 += 5;
-        if self.progress1 > 100 {
-            self.progress1 = 0;
-        }
-        self.progress2 += 10;
-        if self.progress2 > 100 {
-            self.progress2 = 0;
-        }
-        self.progress3 += 1;
-        if self.progress3 > 100 {
-            self.progress3 = 0;
-        }
-        self.progress4 += 3;
-        if self.progress4 > 100 {
-            self.progress4 = 0;
-        }
-    }
-}
-
-enum Event {
-    Input(event::Key),
-    Tick,
-}
-
-fn main() {
-    // Terminal initialization
-    let backend = MouseBackend::new().unwrap();
-    let mut terminal = Terminal::new(backend).unwrap();
-
-    // Channels
-    let (tx, rx) = mpsc::channel();
-    let input_tx = tx.clone();
-    let clock_tx = tx.clone();
-
-    // Input
-    thread::spawn(move || {
-        let stdin = io::stdin();
-        for c in stdin.keys() {
-            let evt = c.unwrap();
-            input_tx.send(Event::Input(evt)).unwrap();
-            if evt == event::Key::Char('q') {
-                break;
-            }
-        }
-    });
-
-    // Tick
-    thread::spawn(move || loop {
-        clock_tx.send(Event::Tick).unwrap();
-        thread::sleep(time::Duration::from_millis(500));
-    });
-
-    // App
-    let mut app = App::new();
-
-    // First draw call
-    terminal.clear().unwrap();
-    terminal.hide_cursor().unwrap();
-    app.size = terminal.size().unwrap();
-    draw(&mut terminal, &app).unwrap();
-
-    loop {
-        let size = terminal.size().unwrap();
-        if size != app.size {
-            terminal.resize(size).unwrap();
-            app.size = size;
-        }
-
-        let evt = rx.recv().unwrap();
-        match evt {
-            Event::Input(input) => if input == event::Key::Char('q') {
-                break;
+    fn start() -> Result<Self> {
+        Ok(App {
+            term: Term::start()?,
+            should_quit: false,
+            state: AppState {
+                progress1: 0,
+                progress2: 0,
+                progress3: 0.0,
+                progress4: 0,
            },
-            Event::Tick => {
-                app.advance();
-            }
-        }
-        draw(&mut terminal, &app).unwrap();
+        })
    }

-    terminal.show_cursor().unwrap();
+    fn stop(&mut self) -> Result<()> {
+        Term::stop()?;
+        Ok(())
+    }
+
+    fn update(&mut self) {
+        self.state.progress1 = (self.state.progress1 + 4).min(100);
+        self.state.progress2 = (self.state.progress2 + 3).min(100);
+        self.state.progress3 = (self.state.progress3 + 0.02).min(1.0);
+        self.state.progress4 = (self.state.progress4 + 1).min(100);
+    }
+
+    fn draw(&mut self) -> Result<()> {
+        self.term.draw(|frame| {
+            let state = self.state;
+            let layout = Self::equal_layout(frame);
+            Self::render_gauge1(state.progress1, frame, layout[0]);
+            Self::render_gauge2(state.progress2, frame, layout[1]);
+            Self::render_gauge3(state.progress3, frame, layout[2]);
+            Self::render_gauge4(state.progress4, frame, layout[3]);
+        })?;
+        Ok(())
+    }
+
+    fn handle_events(&mut self, timeout: Duration) -> io::Result<()> {
+        if event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                if key.kind == KeyEventKind::Press {
+                    if let KeyCode::Char('q') = key.code {
+                        self.should_quit = true;
+                    }
+                }
+            }
+        }
+        Ok(())
+    }
+
+    fn equal_layout(frame: &Frame) -> Rc<[Rect]> {
+        Layout::default()
+            .direction(Direction::Vertical)
+            .constraints([
+                Constraint::Percentage(25),
+                Constraint::Percentage(25),
+                Constraint::Percentage(25),
+                Constraint::Percentage(25),
+            ])
+            .split(frame.size())
+    }
+
+    fn render_gauge1(progress: u16, frame: &mut Frame, area: Rect) {
+        let title = Self::title_block("Gauge with percentage progress");
+        let gauge = Gauge::default()
+            .block(title)
+            .gauge_style(Style::new().light_red())
+            .percent(progress);
+        frame.render_widget(gauge, area);
+    }
+
+    fn render_gauge2(progress: u16, frame: &mut Frame, area: Rect) {
+        let title = Self::title_block("Gauge with percentage progress and custom label");
+        let label = format!("{}/100", progress);
+        let gauge = Gauge::default()
+            .block(title)
+            .gauge_style(Style::new().blue().on_light_blue())
+            .percent(progress)
+            .label(label);
+        frame.render_widget(gauge, area);
+    }
+
+    fn render_gauge3(progress: f64, frame: &mut Frame, area: Rect) {
+        let title =
+            Self::title_block("Gauge with ratio progress, custom label with style, and unicode");
+        let label = Span::styled(
+            format!("{:.2}%", progress * 100.0),
+            Style::new().red().italic().bold(),
+        );
+        let gauge = Gauge::default()
+            .block(title)
+            .gauge_style(Style::default().fg(Color::Yellow))
+            .ratio(progress)
+            .label(label)
+            .use_unicode(true);
+        frame.render_widget(gauge, area);
+    }
+
+    fn render_gauge4(progress: u16, frame: &mut Frame, area: Rect) {
+        let title = Self::title_block("Gauge with percentage progress and label");
+        let label = format!("{}/100", progress);
+        let gauge = Gauge::default()
+            .block(title)
+            .gauge_style(Style::new().green().italic())
+            .percent(progress)
+            .label(label);
+        frame.render_widget(gauge, area);
+    }
+
+    fn title_block(title: &str) -> Block {
+        let title = Title::from(title).alignment(Alignment::Center);
+        Block::default().title(title).borders(Borders::TOP)
+    }
 }

-fn draw(t: &mut Terminal<MouseBackend>, app: &App) -> Result<(), io::Error> {
-    t.draw(|mut f| {
-        let chunks = Layout::default()
-            .direction(Direction::Vertical)
-            .margin(2)
-            .constraints(
-                [
-                    Constraint::Percentage(25),
-                    Constraint::Percentage(25),
-                    Constraint::Percentage(25),
-                    Constraint::Percentage(25),
-                ].as_ref(),
-            )
-            .split(app.size);
-        Gauge::default()
-            .block(Block::default().title("Gauge1").borders(Borders::ALL))
-            .style(Style::default().fg(Color::Yellow))
-            .percent(app.progress1)
-            .render(&mut f, chunks[0]);
-        Gauge::default()
-            .block(Block::default().title("Gauge2").borders(Borders::ALL))
-            .style(Style::default().fg(Color::Magenta).bg(Color::Green))
-            .percent(app.progress2)
-            .label(&format!("{}/100", app.progress2))
-            .render(&mut f, chunks[1]);
-        Gauge::default()
-            .block(Block::default().title("Gauge2").borders(Borders::ALL))
-            .style(Style::default().fg(Color::Yellow))
-            .percent(app.progress3)
-            .render(&mut f, chunks[2]);
-        Gauge::default()
-            .block(Block::default().title("Gauge3").borders(Borders::ALL))
-            .style(Style::default().fg(Color::Cyan).modifier(Modifier::Italic))
-            .percent(app.progress4)
-            .label(&format!("{}/100", app.progress2))
-            .render(&mut f, chunks[3]);
-    })
+struct Term {
+    terminal: Terminal<CrosstermBackend<Stdout>>,
+}
+
+impl Term {
+    pub fn start() -> io::Result<Term> {
+        stdout().execute(EnterAlternateScreen)?;
+        enable_raw_mode()?;
+        let terminal = Terminal::new(CrosstermBackend::new(stdout()))?;
+        Ok(Self { terminal })
+    }
+
+    pub fn stop() -> io::Result<()> {
+        disable_raw_mode()?;
+        stdout().execute(LeaveAlternateScreen)?;
+        Ok(())
+    }
+
+    fn draw(&mut self, frame: impl FnOnce(&mut Frame)) -> Result<()> {
+        self.terminal.draw(frame)?;
+        Ok(())
+    }
 }
--- a/examples/gauge.tape
+++ b/examples/gauge.tape
@@ -0,0 +1,12 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/gauge.tape`
+Output "target/gauge.gif"
+Set Theme "Aardvark Blue"
+Set Width 1200
+Set Height 550
+Hide
+Type "cargo run --example=gauge --features=crossterm"
+Enter
+Sleep 1s
+Show
+Sleep 20s
--- a/examples/generate.bash
+++ b/examples/generate.bash
@@ -0,0 +1,41 @@
+#!/bin/bash
+
+# This script is used to generate the images for the examples README
+# It requires the following tools:
+# - cargo: https://doc.rust-lang.org/cargo/getting-started/installation.html
+# - gh: https://github.com/cli/cli
+# - git: https://git-scm.com/
+# - vhs: https://github.com/charmbracelet/vhs - currently this needs to be installed from the
+#   main branch, as the latest release doesn't support the theme we use or the Screenshot
+#   command. Install using `go install github.com/charmbracelet/vhs@main``
+# - go: https://golang.org/doc/install
+# - ttyd: https://github.com/tsl0922/ttyd
+
+# Exit on error. Append "|| true" if you expect an error.
+set -o errexit
+# Exit on error inside any functions or subshells.
+set -o errtrace
+# Do not allow use of undefined vars. Use ${VAR:-} to use an undefined VAR
+set -o nounset
+# Catch the error in case mysqldump fails (but gzip succeeds) in `mysqldump |gzip`
+set -o pipefail
+# Turn on traces, useful while debugging but commented out by default
+# set -o xtrace
+
+# ensure that running each example doesn't have to wait for the build
+cargo build --examples --features=crossterm,all-widgets
+
+for tape in examples/*.tape; do
+    gif=${tape/examples\//}
+    gif=${gif/.tape/.gif}
+    ~/go/bin/vhs $tape --quiet
+    # this can be pasted into the examples README.md
+    echo "[${gif}]: https://github.com/ratatui-org/ratatui/blob/images/examples/${gif}?raw=true"
+done
+git switch images
+git pull --rebase upstream images
+cp target/*.gif examples/
+git add examples/*.gif
+git commit -m 'docs(examples): update images'
+gh pr create
+git sw -
--- a/examples/hello_world.rs
+++ b/examples/hello_world.rs
@@ -0,0 +1,80 @@
+use std::{
+    io::{self, Stdout},
+    time::Duration,
+};
+
+use anyhow::{Context, Result};
+use crossterm::{
+    event::{self, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{prelude::*, widgets::*};
+
+/// This is a bare minimum example. There are many approaches to running an application loop, so
+/// this is not meant to be prescriptive. It is only meant to demonstrate the basic setup and
+/// teardown of a terminal application.
+///
+/// A more robust application would probably want to handle errors and ensure that the terminal is
+/// restored to a sane state before exiting. This example does not do that. It also does not handle
+/// events or update the application state. It just draws a greeting and exits when the user
+/// presses 'q'.
+fn main() -> Result<()> {
+    let mut terminal = setup_terminal().context("setup failed")?;
+    run(&mut terminal).context("app loop failed")?;
+    restore_terminal(&mut terminal).context("restore terminal failed")?;
+    Ok(())
+}
+
+/// Setup the terminal. This is where you would enable raw mode, enter the alternate screen, and
+/// hide the cursor. This example does not handle errors. A more robust application would probably
+/// want to handle errors and ensure that the terminal is restored to a sane state before exiting.
+fn setup_terminal() -> Result<Terminal<CrosstermBackend<Stdout>>> {
+    let mut stdout = io::stdout();
+    enable_raw_mode().context("failed to enable raw mode")?;
+    execute!(stdout, EnterAlternateScreen).context("unable to enter alternate screen")?;
+    Terminal::new(CrosstermBackend::new(stdout)).context("creating terminal failed")
+}
+
+/// Restore the terminal. This is where you disable raw mode, leave the alternate screen, and show
+/// the cursor.
+fn restore_terminal(terminal: &mut Terminal<CrosstermBackend<Stdout>>) -> Result<()> {
+    disable_raw_mode().context("failed to disable raw mode")?;
+    execute!(terminal.backend_mut(), LeaveAlternateScreen)
+        .context("unable to switch to main screen")?;
+    terminal.show_cursor().context("unable to show cursor")
+}
+
+/// Run the application loop. This is where you would handle events and update the application
+/// state. This example exits when the user presses 'q'. Other styles of application loops are
+/// possible, for example, you could have multiple application states and switch between them based
+/// on events, or you could have a single application state and update it based on events.
+fn run(terminal: &mut Terminal<CrosstermBackend<Stdout>>) -> Result<()> {
+    loop {
+        terminal.draw(crate::render_app)?;
+        if should_quit()? {
+            break;
+        }
+    }
+    Ok(())
+}
+
+/// Render the application. This is where you would draw the application UI. This example just
+/// draws a greeting.
+fn render_app(frame: &mut Frame) {
+    let greeting = Paragraph::new("Hello World! (press 'q' to quit)");
+    frame.render_widget(greeting, frame.size());
+}
+
+/// Check if the user has pressed 'q'. This is where you would handle events. This example just
+/// checks if the user has pressed 'q' and returns true if they have. It does not handle any other
+/// events. There is a 250ms timeout on the event poll so that the application can exit in a timely
+/// manner, and to ensure that the terminal is rendered at least once every 250ms.
+fn should_quit() -> Result<bool> {
+    if event::poll(Duration::from_millis(250)).context("event poll failed")? {
+        if let Event::Key(key) = event::read().context("event read failed")? {
+            return Ok(KeyCode::Char('q') == key.code);
+        }
+    }
+    Ok(false)
+}
--- a/examples/hello_world.tape
+++ b/examples/hello_world.tape
@@ -0,0 +1,12 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/hello_world.tape`
+Output "target/hello_world.gif"
+Set Theme "Aardvark Blue"
+Set Width 1200
+Set Height 200
+Hide
+Type "cargo run --example=hello_world --features=crossterm"
+Enter
+Sleep 1s
+Show
+Sleep 5s
--- a/examples/inline.rs
+++ b/examples/inline.rs
@@ -0,0 +1,281 @@
+use std::{
+    collections::{BTreeMap, VecDeque},
+    error::Error,
+    io,
+    sync::mpsc,
+    thread,
+    time::{Duration, Instant},
+};
+
+use rand::distributions::{Distribution, Uniform};
+use ratatui::{prelude::*, widgets::*};
+
+const NUM_DOWNLOADS: usize = 10;
+
+type DownloadId = usize;
+type WorkerId = usize;
+
+enum Event {
+    Input(crossterm::event::KeyEvent),
+    Tick,
+    Resize,
+    DownloadUpdate(WorkerId, DownloadId, f64),
+    DownloadDone(WorkerId, DownloadId),
+}
+
+struct Downloads {
+    pending: VecDeque<Download>,
+    in_progress: BTreeMap<WorkerId, DownloadInProgress>,
+}
+
+impl Downloads {
+    fn next(&mut self, worker_id: WorkerId) -> Option<Download> {
+        match self.pending.pop_front() {
+            Some(d) => {
+                self.in_progress.insert(
+                    worker_id,
+                    DownloadInProgress {
+                        id: d.id,
+                        started_at: Instant::now(),
+                        progress: 0.0,
+                    },
+                );
+                Some(d)
+            }
+            None => None,
+        }
+    }
+}
+
+struct DownloadInProgress {
+    id: DownloadId,
+    started_at: Instant,
+    progress: f64,
+}
+
+struct Download {
+    id: DownloadId,
+    size: usize,
+}
+
+struct Worker {
+    id: WorkerId,
+    tx: mpsc::Sender<Download>,
+}
+
+fn main() -> Result<(), Box<dyn Error>> {
+    crossterm::terminal::enable_raw_mode()?;
+    let stdout = io::stdout();
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::with_options(
+        backend,
+        TerminalOptions {
+            viewport: Viewport::Inline(8),
+        },
+    )?;
+
+    let (tx, rx) = mpsc::channel();
+    input_handling(tx.clone());
+    let workers = workers(tx);
+    let mut downloads = downloads();
+
+    for w in &workers {
+        let d = downloads.next(w.id).unwrap();
+        w.tx.send(d).unwrap();
+    }
+
+    run_app(&mut terminal, workers, downloads, rx)?;
+
+    crossterm::terminal::disable_raw_mode()?;
+    terminal.clear()?;
+
+    Ok(())
+}
+
+fn input_handling(tx: mpsc::Sender<Event>) {
+    let tick_rate = Duration::from_millis(200);
+    thread::spawn(move || {
+        let mut last_tick = Instant::now();
+        loop {
+            // poll for tick rate duration, if no events, sent tick event.
+            let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+            if crossterm::event::poll(timeout).unwrap() {
+                match crossterm::event::read().unwrap() {
+                    crossterm::event::Event::Key(key) => tx.send(Event::Input(key)).unwrap(),
+                    crossterm::event::Event::Resize(_, _) => tx.send(Event::Resize).unwrap(),
+                    _ => {}
+                };
+            }
+            if last_tick.elapsed() >= tick_rate {
+                tx.send(Event::Tick).unwrap();
+                last_tick = Instant::now();
+            }
+        }
+    });
+}
+
+fn workers(tx: mpsc::Sender<Event>) -> Vec<Worker> {
+    (0..4)
+        .map(|id| {
+            let (worker_tx, worker_rx) = mpsc::channel::<Download>();
+            let tx = tx.clone();
+            thread::spawn(move || {
+                while let Ok(download) = worker_rx.recv() {
+                    let mut remaining = download.size;
+                    while remaining > 0 {
+                        let wait = (remaining as u64).min(10);
+                        thread::sleep(Duration::from_millis(wait * 10));
+                        remaining = remaining.saturating_sub(10);
+                        let progress = (download.size - remaining) * 100 / download.size;
+                        tx.send(Event::DownloadUpdate(id, download.id, progress as f64))
+                            .unwrap();
+                    }
+                    tx.send(Event::DownloadDone(id, download.id)).unwrap();
+                }
+            });
+            Worker { id, tx: worker_tx }
+        })
+        .collect()
+}
+
+fn downloads() -> Downloads {
+    let distribution = Uniform::new(0, 1000);
+    let mut rng = rand::thread_rng();
+    let pending = (0..NUM_DOWNLOADS)
+        .map(|id| {
+            let size = distribution.sample(&mut rng);
+            Download { id, size }
+        })
+        .collect();
+    Downloads {
+        pending,
+        in_progress: BTreeMap::new(),
+    }
+}
+
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    workers: Vec<Worker>,
+    mut downloads: Downloads,
+    rx: mpsc::Receiver<Event>,
+) -> Result<(), Box<dyn Error>> {
+    let mut redraw = true;
+    loop {
+        if redraw {
+            terminal.draw(|f| ui(f, &downloads))?;
+        }
+        redraw = true;
+
+        match rx.recv()? {
+            Event::Input(event) => {
+                if event.code == crossterm::event::KeyCode::Char('q') {
+                    break;
+                }
+            }
+            Event::Resize => {
+                terminal.autoresize()?;
+            }
+            Event::Tick => {}
+            Event::DownloadUpdate(worker_id, _download_id, progress) => {
+                let download = downloads.in_progress.get_mut(&worker_id).unwrap();
+                download.progress = progress;
+                redraw = false
+            }
+            Event::DownloadDone(worker_id, download_id) => {
+                let download = downloads.in_progress.remove(&worker_id).unwrap();
+                terminal.insert_before(1, |buf| {
+                    Paragraph::new(Line::from(vec![
+                        Span::from("Finished "),
+                        Span::styled(
+                            format!("download {download_id}"),
+                            Style::default().add_modifier(Modifier::BOLD),
+                        ),
+                        Span::from(format!(
+                            " in {}ms",
+                            download.started_at.elapsed().as_millis()
+                        )),
+                    ]))
+                    .render(buf.area, buf);
+                })?;
+                match downloads.next(worker_id) {
+                    Some(d) => workers[worker_id].tx.send(d).unwrap(),
+                    None => {
+                        if downloads.in_progress.is_empty() {
+                            terminal.insert_before(1, |buf| {
+                                Paragraph::new("Done !").render(buf.area, buf);
+                            })?;
+                            break;
+                        }
+                    }
+                };
+            }
+        };
+    }
+    Ok(())
+}
+
+fn ui(f: &mut Frame, downloads: &Downloads) {
+    let size = f.size();
+
+    let block = Block::default().title(block::Title::from("Progress").alignment(Alignment::Center));
+    f.render_widget(block, size);
+
+    let chunks = Layout::default()
+        .constraints([Constraint::Length(2), Constraint::Length(4)])
+        .margin(1)
+        .split(size);
+
+    // total progress
+    let done = NUM_DOWNLOADS - downloads.pending.len() - downloads.in_progress.len();
+    let progress = LineGauge::default()
+        .gauge_style(Style::default().fg(Color::Blue))
+        .label(format!("{done}/{NUM_DOWNLOADS}"))
+        .ratio(done as f64 / NUM_DOWNLOADS as f64);
+    f.render_widget(progress, chunks[0]);
+
+    let chunks = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Percentage(20), Constraint::Percentage(80)])
+        .split(chunks[1]);
+
+    // in progress downloads
+    let items: Vec<ListItem> = downloads
+        .in_progress
+        .values()
+        .map(|download| {
+            ListItem::new(Line::from(vec![
+                Span::raw(symbols::DOT),
+                Span::styled(
+                    format!(" download {:>2}", download.id),
+                    Style::default()
+                        .fg(Color::LightGreen)
+                        .add_modifier(Modifier::BOLD),
+                ),
+                Span::raw(format!(
+                    " ({}ms)",
+                    download.started_at.elapsed().as_millis()
+                )),
+            ]))
+        })
+        .collect();
+    let list = List::new(items);
+    f.render_widget(list, chunks[0]);
+
+    for (i, (_, download)) in downloads.in_progress.iter().enumerate() {
+        let gauge = Gauge::default()
+            .gauge_style(Style::default().fg(Color::Yellow))
+            .ratio(download.progress / 100.0);
+        if chunks[1].top().saturating_add(i as u16) > size.bottom() {
+            continue;
+        }
+        f.render_widget(
+            gauge,
+            Rect {
+                x: chunks[1].left(),
+                y: chunks[1].top().saturating_add(i as u16),
+                width: chunks[1].width,
+                height: 1,
+            },
+        );
+    }
+}
--- a/examples/inline.tape
+++ b/examples/inline.tape
@@ -0,0 +1,9 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/inline.tape`
+Output "target/inline.gif"
+Set Theme "Aardvark Blue"
+Set Width 1200
+Set Height 600
+Type "cargo run --example=inline --features=crossterm"
+Enter
+Sleep 20s
--- a/examples/layout.rs
+++ b/examples/layout.rs
@@ -1,107 +1,219 @@
-extern crate log;
-extern crate stderrlog;
-extern crate termion;
-extern crate tui;
+use std::{error::Error, io};

-use std::io;
-use std::sync::mpsc;
-use std::thread;
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use itertools::Itertools;
+use ratatui::{layout::Constraint::*, prelude::*, widgets::*};

-use termion::event;
-use termion::input::TermRead;
+fn main() -> Result<(), Box<dyn Error>> {
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;

-use tui::backend::MouseBackend;
-use tui::layout::{Constraint, Direction, Layout, Rect};
-use tui::widgets::{Block, Borders, Widget};
-use tui::Terminal;
+    // create app and run it
+    let res = run_app(&mut terminal);

-struct App {
-    size: Rect,
-}
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;

-impl App {
-    fn new() -> App {
-        App {
-            size: Rect::default(),
-        }
+    if let Err(err) = res {
+        println!("{err:?}");
    }
+
+    Ok(())
 }

-enum Event {
-    Input(event::Key),
-}
+fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
+    loop {
+        terminal.draw(ui)?;

-fn main() {
-    stderrlog::new().verbosity(4).init().unwrap();
-
-    // Terminal initialization
-    let backend = MouseBackend::new().unwrap();
-    let mut terminal = Terminal::new(backend).unwrap();
-
-    // Channels
-    let (tx, rx) = mpsc::channel();
-    let input_tx = tx.clone();
-
-    // Input
-    thread::spawn(move || {
-        let stdin = io::stdin();
-        for c in stdin.keys() {
-            let evt = c.unwrap();
-            input_tx.send(Event::Input(evt)).unwrap();
-            if evt == event::Key::Char('q') {
-                break;
+        if let Event::Key(key) = event::read()? {
+            if let KeyCode::Char('q') = key.code {
+                return Ok(());
            }
        }
-    });
-
-    // App
-    let mut app = App::new();
-
-    // First draw call
-    terminal.clear().unwrap();
-    terminal.hide_cursor().unwrap();
-    app.size = terminal.size().unwrap();
-    draw(&mut terminal, &app).unwrap();
-
-    loop {
-        let size = terminal.size().unwrap();
-        if size != app.size {
-            terminal.resize(size).unwrap();
-            app.size = size;
-        }
-
-        let evt = rx.recv().unwrap();
-        match evt {
-            Event::Input(input) => if let event::Key::Char('q') = input {
-                break;
-            },
-        }
-        draw(&mut terminal, &app).unwrap();
    }
-
-    terminal.show_cursor().unwrap();
 }

-fn draw(t: &mut Terminal<MouseBackend>, app: &App) -> Result<(), io::Error> {
-    t.draw(|mut f| {
-        let chunks = Layout::default()
-            .direction(Direction::Vertical)
-            .constraints(
-                [
-                    Constraint::Percentage(10),
-                    Constraint::Percentage(80),
-                    Constraint::Percentage(10),
-                ].as_ref(),
-            )
-            .split(app.size);
+fn ui(frame: &mut Frame) {
+    let main_layout = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Length(4),  // text
+            Length(50), // examples
+            Min(0),     // fills remaining space
+        ])
+        .split(frame.size());

-        Block::default()
-            .title("Block")
-            .borders(Borders::ALL)
-            .render(&mut f, chunks[0]);
-        Block::default()
-            .title("Block 2")
-            .borders(Borders::ALL)
-            .render(&mut f, chunks[2]);
-    })
+    // title
+    frame.render_widget(
+        Paragraph::new(vec![
+            Line::from("Horizontal Layout Example. Press q to quit".dark_gray())
+                .alignment(Alignment::Center),
+            Line::from("Each line has 2 constraints, plus Min(0) to fill the remaining space."),
+            Line::from("E.g. the second line of the Len/Min box is [Length(2), Min(2), Min(0)]"),
+            Line::from("Note: constraint labels that don't fit are truncated"),
+        ]),
+        main_layout[0],
+    );
+
+    let example_rows = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Length(9),
+            Length(9),
+            Length(9),
+            Length(9),
+            Length(9),
+            Min(0), // fills remaining space
+        ])
+        .split(main_layout[1]);
+    let example_areas = example_rows
+        .iter()
+        .flat_map(|area| {
+            Layout::default()
+                .direction(Direction::Horizontal)
+                .constraints([
+                    Length(14),
+                    Length(14),
+                    Length(14),
+                    Length(14),
+                    Length(14),
+                    Min(0), // fills remaining space
+                ])
+                .split(*area)
+                .iter()
+                .copied()
+                .take(5) // ignore Min(0)
+                .collect_vec()
+        })
+        .collect_vec();
+
+    // the examples are a cartesian product of the following constraints
+    // e.g. Len/Len, Len/Min, Len/Max, Len/Perc, Len/Ratio, Min/Len, Min/Min, ...
+    let examples = [
+        (
+            "Len",
+            vec![
+                Length(0),
+                Length(2),
+                Length(3),
+                Length(6),
+                Length(10),
+                Length(15),
+            ],
+        ),
+        (
+            "Min",
+            vec![Min(0), Min(2), Min(3), Min(6), Min(10), Min(15)],
+        ),
+        (
+            "Max",
+            vec![Max(0), Max(2), Max(3), Max(6), Max(10), Max(15)],
+        ),
+        (
+            "Perc",
+            vec![
+                Percentage(0),
+                Percentage(25),
+                Percentage(50),
+                Percentage(75),
+                Percentage(100),
+                Percentage(150),
+            ],
+        ),
+        (
+            "Ratio",
+            vec![
+                Ratio(0, 4),
+                Ratio(1, 4),
+                Ratio(2, 4),
+                Ratio(3, 4),
+                Ratio(4, 4),
+                Ratio(6, 4),
+            ],
+        ),
+    ];
+
+    for (i, (a, b)) in examples
+        .iter()
+        .cartesian_product(examples.iter())
+        .enumerate()
+    {
+        let (name_a, examples_a) = a;
+        let (name_b, examples_b) = b;
+        let constraints = examples_a
+            .iter()
+            .copied()
+            .zip(examples_b.iter().copied())
+            .collect_vec();
+        render_example_combination(
+            frame,
+            example_areas[i],
+            &format!("{name_a}/{name_b}"),
+            constraints,
+        );
+    }
+}
+
+/// Renders a single example box
+fn render_example_combination(
+    frame: &mut Frame,
+    area: Rect,
+    title: &str,
+    constraints: Vec<(Constraint, Constraint)>,
+) {
+    let block = Block::default()
+        .title(title.gray())
+        .style(Style::reset())
+        .borders(Borders::ALL)
+        .border_style(Style::default().fg(Color::DarkGray));
+    let inner = block.inner(area);
+    frame.render_widget(block, area);
+    let layout = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints(vec![Length(1); constraints.len() + 1])
+        .split(inner);
+    for (i, (a, b)) in constraints.iter().enumerate() {
+        render_single_example(frame, layout[i], vec![*a, *b, Min(0)]);
+    }
+    // This is to make it easy to visually see the alignment of the examples
+    // with the constraints.
+    frame.render_widget(Paragraph::new("123456789012"), layout[6]);
+}
+
+/// Renders a single example line
+fn render_single_example(frame: &mut Frame, area: Rect, constraints: Vec<Constraint>) {
+    let red = Paragraph::new(constraint_label(constraints[0])).on_red();
+    let blue = Paragraph::new(constraint_label(constraints[1])).on_blue();
+    let green = Paragraph::new("·".repeat(12)).on_green();
+    let layout = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints(constraints)
+        .split(area);
+    frame.render_widget(red, layout[0]);
+    frame.render_widget(blue, layout[1]);
+    frame.render_widget(green, layout[2]);
+}
+
+fn constraint_label(constraint: Constraint) -> String {
+    match constraint {
+        Length(n) => format!("{n}"),
+        Min(n) => format!("{n}"),
+        Max(n) => format!("{n}"),
+        Percentage(n) => format!("{n}"),
+        Ratio(a, b) => format!("{a}:{b}"),
+    }
 }
--- a/examples/layout.tape
+++ b/examples/layout.tape
@@ -0,0 +1,12 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/layout.tape`
+Output "target/layout.gif"
+Set Theme "Aardvark Blue"
+Set Width 1200
+Set Height 1410
+Hide
+Type "cargo run --example=layout --features=crossterm"
+Enter
+Sleep 1s
+Show
+Sleep 2s
--- a/examples/list.rs
+++ b/examples/list.rs
@@ -1,41 +1,103 @@
-extern crate termion;
-extern crate tui;
+use std::{
+    error::Error,
+    io,
+    time::{Duration, Instant},
+};

-use std::io;
-use std::sync::mpsc;
-use std::thread;
-use std::time;
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{prelude::*, widgets::*};

-use termion::event;
-use termion::input::TermRead;
+struct StatefulList<T> {
+    state: ListState,
+    items: Vec<T>,
+}

-use tui::backend::MouseBackend;
-use tui::layout::{Constraint, Corner, Direction, Layout, Rect};
-use tui::style::{Color, Modifier, Style};
-use tui::widgets::{Block, Borders, Item, List, SelectableList, Widget};
-use tui::Terminal;
+impl<T> StatefulList<T> {
+    fn with_items(items: Vec<T>) -> StatefulList<T> {
+        StatefulList {
+            state: ListState::default(),
+            items,
+        }
+    }

+    fn next(&mut self) {
+        let i = match self.state.selected() {
+            Some(i) => {
+                if i >= self.items.len() - 1 {
+                    0
+                } else {
+                    i + 1
+                }
+            }
+            None => 0,
+        };
+        self.state.select(Some(i));
+    }
+
+    fn previous(&mut self) {
+        let i = match self.state.selected() {
+            Some(i) => {
+                if i == 0 {
+                    self.items.len() - 1
+                } else {
+                    i - 1
+                }
+            }
+            None => 0,
+        };
+        self.state.select(Some(i));
+    }
+
+    fn unselect(&mut self) {
+        self.state.select(None);
+    }
+}
+
+/// This struct holds the current state of the app. In particular, it has the `items` field which is
+/// a wrapper around `ListState`. Keeping track of the items state let us render the associated
+/// widget with its state and have access to features such as natural scrolling.
+///
+/// Check the event handling at the bottom to see how to change the state on incoming events.
+/// Check the drawing logic for items on how to specify the highlighting style for selected items.
 struct App<'a> {
-    size: Rect,
-    items: Vec<&'a str>,
-    selected: Option<usize>,
+    items: StatefulList<(&'a str, usize)>,
    events: Vec<(&'a str, &'a str)>,
-    info_style: Style,
-    warning_style: Style,
-    error_style: Style,
-    critical_style: Style,
 }

 impl<'a> App<'a> {
    fn new() -> App<'a> {
        App {
-            size: Rect::default(),
-            items: vec![
-                "Item1", "Item2", "Item3", "Item4", "Item5", "Item6", "Item7", "Item8", "Item9",
-                "Item10", "Item11", "Item12", "Item13", "Item14", "Item15", "Item16", "Item17",
-                "Item18", "Item19", "Item20", "Item21", "Item22", "Item23", "Item24",
-            ],
-            selected: None,
+            items: StatefulList::with_items(vec![
+                ("Item0", 1),
+                ("Item1", 2),
+                ("Item2", 1),
+                ("Item3", 3),
+                ("Item4", 1),
+                ("Item5", 4),
+                ("Item6", 1),
+                ("Item7", 3),
+                ("Item8", 1),
+                ("Item9", 6),
+                ("Item10", 1),
+                ("Item11", 3),
+                ("Item12", 1),
+                ("Item13", 2),
+                ("Item14", 1),
+                ("Item15", 1),
+                ("Item16", 4),
+                ("Item17", 1),
+                ("Item18", 5),
+                ("Item19", 4),
+                ("Item20", 1),
+                ("Item21", 2),
+                ("Item22", 1),
+                ("Item23", 3),
+                ("Item24", 1),
+            ]),
            events: vec![
                ("Event1", "INFO"),
                ("Event2", "INFO"),
@@ -64,144 +126,153 @@ impl<'a> App<'a> {
                ("Event25", "INFO"),
                ("Event26", "INFO"),
            ],
-            info_style: Style::default().fg(Color::White),
-            warning_style: Style::default().fg(Color::Yellow),
-            error_style: Style::default().fg(Color::Magenta),
-            critical_style: Style::default().fg(Color::Red),
        }
    }

-    fn advance(&mut self) {
-        let event = self.events.pop().unwrap();
-        self.events.insert(0, event);
+    /// Rotate through the event list.
+    /// This only exists to simulate some kind of "progress"
+    fn on_tick(&mut self) {
+        let event = self.events.remove(0);
+        self.events.push(event);
    }
 }

-enum Event {
-    Input(event::Key),
-    Tick,
+fn main() -> Result<(), Box<dyn Error>> {
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+
+    // create app and run it
+    let tick_rate = Duration::from_millis(250);
+    let app = App::new();
+    let res = run_app(&mut terminal, app, tick_rate);
+
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
+
+    if let Err(err) = res {
+        println!("{err:?}");
+    }
+
+    Ok(())
 }

-fn main() {
-    // Terminal initialization
-    let backend = MouseBackend::new().unwrap();
-    let mut terminal = Terminal::new(backend).unwrap();
-
-    // Channels
-    let (tx, rx) = mpsc::channel();
-    let input_tx = tx.clone();
-    let clock_tx = tx.clone();
-
-    // Input
-    thread::spawn(move || {
-        let stdin = io::stdin();
-        for c in stdin.keys() {
-            let evt = c.unwrap();
-            input_tx.send(Event::Input(evt)).unwrap();
-            if evt == event::Key::Char('q') {
-                break;
-            }
-        }
-    });
-
-    // Tick
-    thread::spawn(move || loop {
-        clock_tx.send(Event::Tick).unwrap();
-        thread::sleep(time::Duration::from_millis(500));
-    });
-
-    // App
-    let mut app = App::new();
-
-    // First draw call
-    terminal.clear().unwrap();
-    terminal.hide_cursor().unwrap();
-    app.size = terminal.size().unwrap();
-    draw(&mut terminal, &app).unwrap();
-
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    mut app: App,
+    tick_rate: Duration,
+) -> io::Result<()> {
+    let mut last_tick = Instant::now();
    loop {
-        let size = terminal.size().unwrap();
-        if size != app.size {
-            terminal.resize(size).unwrap();
-            app.size = size;
-        }
+        terminal.draw(|f| ui(f, &mut app))?;

-        let evt = rx.recv().unwrap();
-        match evt {
-            Event::Input(input) => match input {
-                event::Key::Char('q') => {
-                    break;
-                }
-                event::Key::Left => {
-                    app.selected = None;
-                }
-                event::Key::Down => {
-                    app.selected = if let Some(selected) = app.selected {
-                        if selected >= app.items.len() - 1 {
-                            Some(0)
-                        } else {
-                            Some(selected + 1)
-                        }
-                    } else {
-                        Some(0)
+        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+        if crossterm::event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                if key.kind == KeyEventKind::Press {
+                    match key.code {
+                        KeyCode::Char('q') => return Ok(()),
+                        KeyCode::Left => app.items.unselect(),
+                        KeyCode::Down => app.items.next(),
+                        KeyCode::Up => app.items.previous(),
+                        _ => {}
                    }
                }
-                event::Key::Up => {
-                    app.selected = if let Some(selected) = app.selected {
-                        if selected > 0 {
-                            Some(selected - 1)
-                        } else {
-                            Some(app.items.len() - 1)
-                        }
-                    } else {
-                        Some(0)
-                    }
-                }
-                _ => {}
-            },
-            Event::Tick => {
-                app.advance();
            }
        }
-        draw(&mut terminal, &app).unwrap();
-    }
-
-    terminal.show_cursor().unwrap();
-    terminal.clear().unwrap();
-}
-
-fn draw(t: &mut Terminal<MouseBackend>, app: &App) -> Result<(), io::Error> {
-    t.draw(|mut f| {
-        let chunks = Layout::default()
-            .direction(Direction::Horizontal)
-            .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-            .split(app.size);
-
-        let style = Style::default().fg(Color::Black).bg(Color::White);
-        SelectableList::default()
-            .block(Block::default().borders(Borders::ALL).title("List"))
-            .items(&app.items)
-            .select(app.selected)
-            .style(style)
-            .highlight_style(style.fg(Color::LightGreen).modifier(Modifier::Bold))
-            .highlight_symbol(">")
-            .render(&mut f, chunks[0]);
-        {
-            let events = app.events.iter().map(|&(evt, level)| {
-                Item::StyledData(
-                    format!("{}: {}", level, evt),
-                    match level {
-                        "ERROR" => &app.error_style,
-                        "CRITICAL" => &app.critical_style,
-                        "WARNING" => &app.warning_style,
-                        _ => &app.info_style,
-                    },
-                )
-            });
-            List::new(events)
-                .block(Block::default().borders(Borders::ALL).title("List"))
-                .start_corner(Corner::BottomLeft)
-                .render(&mut f, chunks[1]);
+        if last_tick.elapsed() >= tick_rate {
+            app.on_tick();
+            last_tick = Instant::now();
        }
-    })
+    }
+}
+
+fn ui(f: &mut Frame, app: &mut App) {
+    // Create two chunks with equal horizontal screen space
+    let chunks = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
+        .split(f.size());
+
+    // Iterate through all elements in the `items` app and append some debug text to it.
+    let items: Vec<ListItem> = app
+        .items
+        .items
+        .iter()
+        .map(|i| {
+            let mut lines = vec![Line::from(i.0)];
+            for _ in 0..i.1 {
+                lines.push(
+                    "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
+                        .italic()
+                        .into(),
+                );
+            }
+            ListItem::new(lines).style(Style::default().fg(Color::Black).bg(Color::White))
+        })
+        .collect();
+
+    // Create a List from all list items and highlight the currently selected one
+    let items = List::new(items)
+        .block(Block::default().borders(Borders::ALL).title("List"))
+        .highlight_style(
+            Style::default()
+                .bg(Color::LightGreen)
+                .add_modifier(Modifier::BOLD),
+        )
+        .highlight_symbol(">> ");
+
+    // We can now render the item list
+    f.render_stateful_widget(items, chunks[0], &mut app.items.state);
+
+    // Let's do the same for the events.
+    // The event list doesn't have any state and only displays the current state of the list.
+    let events: Vec<ListItem> = app
+        .events
+        .iter()
+        .rev()
+        .map(|&(event, level)| {
+            // Colorcode the level depending on its type
+            let s = match level {
+                "CRITICAL" => Style::default().fg(Color::Red),
+                "ERROR" => Style::default().fg(Color::Magenta),
+                "WARNING" => Style::default().fg(Color::Yellow),
+                "INFO" => Style::default().fg(Color::Blue),
+                _ => Style::default(),
+            };
+            // Add a example datetime and apply proper spacing between them
+            let header = Line::from(vec![
+                Span::styled(format!("{level:<9}"), s),
+                " ".into(),
+                "2020-01-01 10:00:00".italic(),
+            ]);
+            // The event gets its own line
+            let log = Line::from(vec![event.into()]);
+
+            // Here several things happen:
+            // 1. Add a `---` spacing line above the final list entry
+            // 2. Add the Level + datetime
+            // 3. Add a spacer line
+            // 4. Add the actual event
+            ListItem::new(vec![
+                Line::from("-".repeat(chunks[1].width as usize)),
+                header,
+                Line::from(""),
+                log,
+            ])
+        })
+        .collect();
+    let events_list = List::new(events)
+        .block(Block::default().borders(Borders::ALL).title("List"))
+        .start_corner(Corner::BottomLeft);
+    f.render_widget(events_list, chunks[1]);
 }
--- a/examples/list.tape
+++ b/examples/list.tape
@@ -0,0 +1,15 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/list.tape`
+Output "target/list.gif"
+Set Theme "Aardvark Blue"
+Set Width 1200
+Set Height 600
+Hide
+Type "cargo run --example=list --features=crossterm"
+Enter
+Sleep 1s
+Show
+Down@1s 4
+Up@1s 2
+Left@1s 1
+Sleep 5s
--- a/examples/modifiers.rs
+++ b/examples/modifiers.rs
@@ -0,0 +1,116 @@
+/// This example is useful for testing how your terminal emulator handles different modifiers.
+/// It will render a grid of combinations of foreground and background colors with all
+/// modifiers applied to them.
+use std::{
+    error::Error,
+    io::{self, Stdout},
+    iter::once,
+    result,
+    time::Duration,
+};
+
+use crossterm::{
+    event::{self, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use itertools::Itertools;
+use ratatui::{prelude::*, widgets::*};
+
+type Result<T> = result::Result<T, Box<dyn Error>>;
+
+fn main() -> Result<()> {
+    let mut terminal = setup_terminal()?;
+    let res = run_app(&mut terminal);
+    restore_terminal(terminal)?;
+    if let Err(err) = res {
+        eprintln!("{err:?}");
+    }
+    Ok(())
+}
+
+fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
+    loop {
+        terminal.draw(ui)?;
+
+        if event::poll(Duration::from_millis(250))? {
+            if let Event::Key(key) = event::read()? {
+                if let KeyCode::Char('q') = key.code {
+                    return Ok(());
+                }
+            }
+        }
+    }
+}
+
+fn ui(frame: &mut Frame) {
+    let layout = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Length(1), Constraint::Min(0)])
+        .split(frame.size());
+    frame.render_widget(
+        Paragraph::new("Note: not all terminals support all modifiers")
+            .style(Style::default().fg(Color::Red).add_modifier(Modifier::BOLD)),
+        layout[0],
+    );
+    let layout = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Length(1); 50])
+        .split(layout[1])
+        .iter()
+        .flat_map(|area| {
+            Layout::default()
+                .direction(Direction::Horizontal)
+                .constraints([Constraint::Percentage(20); 5])
+                .split(*area)
+                .to_vec()
+        })
+        .collect_vec();
+
+    let colors = [
+        Color::Black,
+        Color::DarkGray,
+        Color::Gray,
+        Color::White,
+        Color::Red,
+    ];
+    let all_modifiers = once(Modifier::empty())
+        .chain(Modifier::all().iter())
+        .collect_vec();
+    let mut index = 0;
+    for bg in colors.iter() {
+        for fg in colors.iter() {
+            for modifier in &all_modifiers {
+                let modifier_name = format!("{modifier:11?}");
+                let padding = (" ").repeat(12 - modifier_name.len());
+                let paragraph = Paragraph::new(Line::from(vec![
+                    modifier_name.fg(*fg).bg(*bg).add_modifier(*modifier),
+                    padding.fg(*fg).bg(*bg).add_modifier(*modifier),
+                    // This is a hack to work around a bug in VHS which is used for rendering the
+                    // examples to gifs. The bug is that the background color of a paragraph seems
+                    // to bleed into the next character.
+                    ".".black().on_black(),
+                ]));
+                frame.render_widget(paragraph, layout[index]);
+                index += 1;
+            }
+        }
+    }
+}
+
+fn setup_terminal() -> Result<Terminal<CrosstermBackend<Stdout>>> {
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+    terminal.hide_cursor()?;
+    Ok(terminal)
+}
+
+fn restore_terminal(mut terminal: Terminal<CrosstermBackend<Stdout>>) -> Result<()> {
+    disable_raw_mode()?;
+    execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
+    terminal.show_cursor()?;
+    Ok(())
+}
--- a/examples/modifiers.tape
+++ b/examples/modifiers.tape
@@ -0,0 +1,12 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/modifiers.tape`
+Output "target/modifiers.gif"
+Set Theme "Aardvark Blue"
+Set Width 1200
+Set Height 1460
+Hide
+Type "cargo run --example=modifiers --features=crossterm"
+Enter
+Sleep 2s
+Show
+Sleep 1s
--- a/examples/panic.rs
+++ b/examples/panic.rs
@@ -0,0 +1,134 @@
+//! How to use a panic hook to reset the terminal before printing the panic to
+//! the terminal.
+//!
+//! When exiting normally or when handling `Result::Err`, we can reset the
+//! terminal manually at the end of `main` just before we print the error.
+//!
+//! Because a panic interrupts the normal control flow, manually resetting the
+//! terminal at the end of `main` won't do us any good. Instead, we need to
+//! make sure to set up a panic hook that first resets the terminal before
+//! handling the panic. This both reuses the standard panic hook to ensure a
+//! consistent panic handling UX and properly resets the terminal to not
+//! distort the output.
+//!
+//! That's why this example is set up to show both situations, with and without
+//! the chained panic hook, to see the difference.
+
+use std::{error::Error, io};
+
+use crossterm::{
+    event::{self, Event, KeyCode},
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{prelude::*, widgets::*};
+
+type Result<T> = std::result::Result<T, Box<dyn Error>>;
+
+#[derive(Default)]
+struct App {
+    hook_enabled: bool,
+}
+
+impl App {
+    fn chain_hook(&mut self) {
+        let original_hook = std::panic::take_hook();
+
+        std::panic::set_hook(Box::new(move |panic| {
+            reset_terminal().unwrap();
+            original_hook(panic);
+        }));
+
+        self.hook_enabled = true;
+    }
+}
+
+fn main() -> Result<()> {
+    let mut terminal = init_terminal()?;
+
+    let mut app = App::default();
+    let res = run_tui(&mut terminal, &mut app);
+
+    reset_terminal()?;
+
+    if let Err(err) = res {
+        println!("{err:?}");
+    }
+
+    Ok(())
+}
+
+/// Initializes the terminal.
+fn init_terminal() -> Result<Terminal<CrosstermBackend<io::Stdout>>> {
+    crossterm::execute!(io::stdout(), EnterAlternateScreen)?;
+    enable_raw_mode()?;
+
+    let backend = CrosstermBackend::new(io::stdout());
+
+    let mut terminal = Terminal::new(backend)?;
+    terminal.hide_cursor()?;
+
+    Ok(terminal)
+}
+
+/// Resets the terminal.
+fn reset_terminal() -> Result<()> {
+    disable_raw_mode()?;
+    crossterm::execute!(io::stdout(), LeaveAlternateScreen)?;
+
+    Ok(())
+}
+
+/// Runs the TUI loop.
+fn run_tui<B: Backend>(terminal: &mut Terminal<B>, app: &mut App) -> io::Result<()> {
+    loop {
+        terminal.draw(|f| ui(f, app))?;
+
+        if let Event::Key(key) = event::read()? {
+            match key.code {
+                KeyCode::Char('p') => {
+                    panic!("intentional demo panic");
+                }
+
+                KeyCode::Char('e') => {
+                    app.chain_hook();
+                }
+
+                _ => {
+                    return Ok(());
+                }
+            }
+        }
+    }
+}
+
+/// Render the TUI.
+fn ui(f: &mut Frame, app: &App) {
+    let text = vec![
+        if app.hook_enabled {
+            Line::from("HOOK IS CURRENTLY **ENABLED**")
+        } else {
+            Line::from("HOOK IS CURRENTLY **DISABLED**")
+        },
+        Line::from(""),
+        Line::from("press `p` to panic"),
+        Line::from("press `e` to enable the terminal-resetting panic hook"),
+        Line::from("press any other key to quit without panic"),
+        Line::from(""),
+        Line::from("when you panic without the chained hook,"),
+        Line::from("you will likely have to reset your terminal afterwards"),
+        Line::from("with the `reset` command"),
+        Line::from(""),
+        Line::from("with the chained panic hook enabled,"),
+        Line::from("you should see the panic report as you would without ratatui"),
+        Line::from(""),
+        Line::from("try first without the panic handler to see the difference"),
+    ];
+
+    let b = Block::default()
+        .title("Panic Handler Demo")
+        .borders(Borders::ALL);
+
+    let p = Paragraph::new(text).block(b).alignment(Alignment::Center);
+
+    f.render_widget(p, f.size());
+}
--- a/examples/panic.tape
+++ b/examples/panic.tape
@@ -0,0 +1,20 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/panic.tape`
+Output "target/panic.gif"
+Set Theme "Aardvark Blue"
+Set Width 1200
+Set Height 600
+Type "cargo run --example=panic --features=crossterm"
+Enter
+Sleep 5s
+Type p
+Sleep 2s
+Type reset
+Enter
+Type "cargo run --example=panic --features=crossterm"
+Enter
+Sleep 2s
+Type e
+Sleep 2s
+Type p
+Sleep 5s
--- a/examples/paragraph.rs
+++ b/examples/paragraph.rs
@@ -1,83 +1,154 @@
-extern crate termion;
-extern crate tui;
+use std::{
+    error::Error,
+    io,
+    time::{Duration, Instant},
+};

-use std::io;
-use termion::event;
-use termion::input::TermRead;
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{prelude::*, widgets::*};

-use tui::backend::MouseBackend;
-use tui::layout::{Alignment, Constraint, Direction, Layout, Rect};
-use tui::style::{Color, Modifier, Style};
-use tui::widgets::{Block, Paragraph, Text, Widget};
-use tui::Terminal;
+struct App {
+    scroll: u16,
+}

-fn main() {
-    let mut terminal = Terminal::new(MouseBackend::new().unwrap()).unwrap();
-    let stdin = io::stdin();
-    terminal.clear().unwrap();
-    terminal.hide_cursor().unwrap();
+impl App {
+    fn new() -> App {
+        App { scroll: 0 }
+    }

-    let mut term_size = terminal.size().unwrap();
-    draw(&mut terminal, term_size).unwrap();
+    fn on_tick(&mut self) {
+        self.scroll += 1;
+        self.scroll %= 10;
+    }
+}

-    for c in stdin.keys() {
-        let size = terminal.size().unwrap();
-        if size != term_size {
-            terminal.resize(size).unwrap();
-            term_size = size;
+fn main() -> Result<(), Box<dyn Error>> {
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+
+    // create app and run it
+    let tick_rate = Duration::from_millis(250);
+    let app = App::new();
+    let res = run_app(&mut terminal, app, tick_rate);
+
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
+
+    if let Err(err) = res {
+        println!("{err:?}");
+    }
+
+    Ok(())
+}
+
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    mut app: App,
+    tick_rate: Duration,
+) -> io::Result<()> {
+    let mut last_tick = Instant::now();
+    loop {
+        terminal.draw(|f| ui(f, &app))?;
+
+        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+        if crossterm::event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                if let KeyCode::Char('q') = key.code {
+                    return Ok(());
+                }
+            }
        }
-
-        draw(&mut terminal, term_size).unwrap();
-        let evt = c.unwrap();
-        if evt == event::Key::Char('q') {
-            break;
+        if last_tick.elapsed() >= tick_rate {
+            app.on_tick();
+            last_tick = Instant::now();
        }
    }
-    terminal.show_cursor().unwrap();
 }

-fn draw(t: &mut Terminal<MouseBackend>, size: Rect) -> Result<(), io::Error> {
-    t.draw(|mut f| {
+fn ui(f: &mut Frame, app: &App) {
+    let size = f.size();
+
+    // Words made "loooong" to demonstrate line breaking.
+    let s = "Veeeeeeeeeeeeeeeery    loooooooooooooooooong   striiiiiiiiiiiiiiiiiiiiiiiiiing.   ";
+    let mut long_line = s.repeat(usize::from(size.width) / s.len() + 4);
+    long_line.push('\n');
+
+    let block = Block::default().black();
+    f.render_widget(block, size);
+
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+        ])
+        .split(size);
+
+    let text = vec![
+        Line::from("This is a line "),
+        Line::from("This is a line   ".red()),
+        Line::from("This is a line".on_blue()),
+        Line::from("This is a longer line".crossed_out()),
+        Line::from(long_line.on_green()),
+        Line::from("This is a line".green().italic()),
+        Line::from(vec![
+            "Masked text: ".into(),
+            Span::styled(
+                Masked::new("password", '*'),
+                Style::default().fg(Color::Red),
+            ),
+        ]),
+    ];
+
+    let create_block = |title| {
        Block::default()
-            .style(Style::default().bg(Color::White))
-            .render(&mut f, size);
+            .borders(Borders::ALL)
+            .style(Style::default().fg(Color::Gray))
+            .title(Span::styled(
+                title,
+                Style::default().add_modifier(Modifier::BOLD),
+            ))
+    };

-        let chunks = Layout::default()
-            .direction(Direction::Vertical)
-            .margin(5)
-            .constraints(
-                [
-                    Constraint::Percentage(30),
-                    Constraint::Percentage(30),
-                    Constraint::Percentage(30),
-                ].as_ref(),
-            )
-            .split(size);
+    let paragraph = Paragraph::new(text.clone())
+        .style(Style::default().fg(Color::Gray))
+        .block(create_block("Default alignment (Left), no wrap"));
+    f.render_widget(paragraph, chunks[0]);

-        let text = [
-            Text::Data("This a line\n"),
-            Text::StyledData("This a line\n", Style::default().fg(Color::Red)),
-            Text::StyledData("This a line\n", Style::default().bg(Color::Blue)),
-            Text::StyledData(
-                "This a longer line\n",
-                Style::default().modifier(Modifier::CrossedOut),
-            ),
-            Text::StyledData(
-                "This a line\n",
-                Style::default().fg(Color::Green).modifier(Modifier::Italic),
-            ),
-        ];
+    let paragraph = Paragraph::new(text.clone())
+        .style(Style::default().fg(Color::Gray))
+        .block(create_block("Default alignment (Left), with wrap"))
+        .wrap(Wrap { trim: true });
+    f.render_widget(paragraph, chunks[1]);

-        Paragraph::new(text.iter())
-            .alignment(Alignment::Left)
-            .render(&mut f, chunks[0]);
-        Paragraph::new(text.iter())
-            .alignment(Alignment::Center)
-            .wrap(true)
-            .render(&mut f, chunks[1]);
-        Paragraph::new(text.iter())
-            .alignment(Alignment::Right)
-            .wrap(true)
-            .render(&mut f, chunks[2]);
-    })
+    let paragraph = Paragraph::new(text.clone())
+        .style(Style::default().fg(Color::Gray))
+        .block(create_block("Right alignment, with wrap"))
+        .alignment(Alignment::Right)
+        .wrap(Wrap { trim: true });
+    f.render_widget(paragraph, chunks[2]);
+
+    let paragraph = Paragraph::new(text)
+        .style(Style::default().fg(Color::Gray))
+        .block(create_block("Center alignment, with wrap, with scroll"))
+        .alignment(Alignment::Center)
+        .wrap(Wrap { trim: true })
+        .scroll((app.scroll, 0));
+    f.render_widget(paragraph, chunks[3]);
 }
--- a/examples/paragraph.tape
+++ b/examples/paragraph.tape
@@ -0,0 +1,12 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/paragraph.tape`
+Output "target/paragraph.gif"
+Set Theme "Aardvark Blue"
+Set Width 1200
+Set Height 1800
+Hide
+Type "cargo run --example=paragraph --features=crossterm"
+Enter
+Sleep 1s
+Show
+Sleep 5s
--- a/examples/popup.rs
+++ b/examples/popup.rs
@@ -0,0 +1,114 @@
+use std::{error::Error, io};
+
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{prelude::*, widgets::*};
+
+struct App {
+    show_popup: bool,
+}
+
+impl App {
+    fn new() -> App {
+        App { show_popup: false }
+    }
+}
+
+fn main() -> Result<(), Box<dyn Error>> {
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+
+    // create app and run it
+    let app = App::new();
+    let res = run_app(&mut terminal, app);
+
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
+
+    if let Err(err) = res {
+        println!("{err:?}");
+    }
+
+    Ok(())
+}
+
+fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<()> {
+    loop {
+        terminal.draw(|f| ui(f, &app))?;
+
+        if let Event::Key(key) = event::read()? {
+            if key.kind == KeyEventKind::Press {
+                match key.code {
+                    KeyCode::Char('q') => return Ok(()),
+                    KeyCode::Char('p') => app.show_popup = !app.show_popup,
+                    _ => {}
+                }
+            }
+        }
+    }
+}
+
+fn ui(f: &mut Frame, app: &App) {
+    let size = f.size();
+
+    let chunks = Layout::default()
+        .constraints([Constraint::Percentage(20), Constraint::Percentage(80)])
+        .split(size);
+
+    let text = if app.show_popup {
+        "Press p to close the popup"
+    } else {
+        "Press p to show the popup"
+    };
+    let paragraph = Paragraph::new(text.slow_blink())
+        .alignment(Alignment::Center)
+        .wrap(Wrap { trim: true });
+    f.render_widget(paragraph, chunks[0]);
+
+    let block = Block::default()
+        .title("Content")
+        .borders(Borders::ALL)
+        .on_blue();
+    f.render_widget(block, chunks[1]);
+
+    if app.show_popup {
+        let block = Block::default().title("Popup").borders(Borders::ALL);
+        let area = centered_rect(60, 20, size);
+        f.render_widget(Clear, area); //this clears out the background
+        f.render_widget(block, area);
+    }
+}
+
+/// helper function to create a centered rect using up certain percentage of the available rect `r`
+fn centered_rect(percent_x: u16, percent_y: u16, r: Rect) -> Rect {
+    let popup_layout = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Percentage((100 - percent_y) / 2),
+            Constraint::Percentage(percent_y),
+            Constraint::Percentage((100 - percent_y) / 2),
+        ])
+        .split(r);
+
+    Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([
+            Constraint::Percentage((100 - percent_x) / 2),
+            Constraint::Percentage(percent_x),
+            Constraint::Percentage((100 - percent_x) / 2),
+        ])
+        .split(popup_layout[1])[1]
+}
--- a/examples/popup.tape
+++ b/examples/popup.tape
@@ -0,0 +1,16 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/popup.tape`
+Output "target/popup.gif"
+Set Theme "Aardvark Blue"
+Set Width 1200
+Set Height 600
+Hide
+Type "cargo run --example=popup --features=crossterm"
+Enter
+Sleep 1s
+Show
+Sleep 2s
+Type p
+Sleep 2s
+Type p
+Sleep 5s
--- a/examples/rustbox.rs
+++ b/examples/rustbox.rs
@@ -1,48 +0,0 @@
-extern crate rustbox;
-extern crate tui;
-
-use rustbox::Key;
-use std::error::Error;
-
-use tui::backend::RustboxBackend;
-use tui::layout::{Constraint, Direction, Layout};
-use tui::style::{Color, Modifier, Style};
-use tui::widgets::{Block, Borders, Paragraph, Widget};
-use tui::Terminal;
-
-fn main() {
-    let mut terminal = Terminal::new(RustboxBackend::new().unwrap()).unwrap();
-    terminal.clear().unwrap();
-    terminal.hide_cursor().unwrap();
-    draw(&mut terminal);
-    loop {
-        match terminal.backend().rustbox().poll_event(false) {
-            Ok(rustbox::Event::KeyEvent(key)) => if key == Key::Char('q') {
-                break;
-            },
-            Err(e) => panic!("{}", e.description()),
-            _ => {}
-        };
-        draw(&mut terminal);
-    }
-    terminal.show_cursor().unwrap();
-}
-
-fn draw(t: &mut Terminal<RustboxBackend>) {
-    let size = t.size().unwrap();
-    {
-        let mut f = t.get_frame();
-        Paragraph::default()
-            .block(
-                Block::default()
-                    .title("Rustbox backend")
-                    .title_style(Style::default().fg(Color::Yellow).modifier(Modifier::Bold))
-                    .borders(Borders::ALL)
-                    .border_style(Style::default().fg(Color::Magenta)),
-            )
-            .text("It {yellow works}!")
-            .render(&mut f, &size);
-    }
-
-    t.draw().unwrap();
-}
--- a/examples/scrollbar.rs
+++ b/examples/scrollbar.rs
@@ -0,0 +1,235 @@
+use std::{
+    error::Error,
+    io,
+    time::{Duration, Instant},
+};
+
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{prelude::*, symbols::scrollbar, widgets::*};
+
+#[derive(Default)]
+struct App {
+    pub vertical_scroll_state: ScrollbarState,
+    pub horizontal_scroll_state: ScrollbarState,
+    pub vertical_scroll: usize,
+    pub horizontal_scroll: usize,
+}
+
+fn main() -> Result<(), Box<dyn Error>> {
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+
+    // create app and run it
+    let tick_rate = Duration::from_millis(250);
+    let app = App::default();
+    let res = run_app(&mut terminal, app, tick_rate);
+
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
+
+    if let Err(err) = res {
+        println!("{err:?}");
+    }
+
+    Ok(())
+}
+
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    mut app: App,
+    tick_rate: Duration,
+) -> io::Result<()> {
+    let mut last_tick = Instant::now();
+    loop {
+        terminal.draw(|f| ui(f, &mut app))?;
+
+        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+        if crossterm::event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                match key.code {
+                    KeyCode::Char('q') => return Ok(()),
+                    KeyCode::Char('j') => {
+                        app.vertical_scroll = app.vertical_scroll.saturating_add(1);
+                        app.vertical_scroll_state =
+                            app.vertical_scroll_state.position(app.vertical_scroll);
+                    }
+                    KeyCode::Char('k') => {
+                        app.vertical_scroll = app.vertical_scroll.saturating_sub(1);
+                        app.vertical_scroll_state =
+                            app.vertical_scroll_state.position(app.vertical_scroll);
+                    }
+                    KeyCode::Char('h') => {
+                        app.horizontal_scroll = app.horizontal_scroll.saturating_sub(1);
+                        app.horizontal_scroll_state =
+                            app.horizontal_scroll_state.position(app.horizontal_scroll);
+                    }
+                    KeyCode::Char('l') => {
+                        app.horizontal_scroll = app.horizontal_scroll.saturating_add(1);
+                        app.horizontal_scroll_state =
+                            app.horizontal_scroll_state.position(app.horizontal_scroll);
+                    }
+                    _ => {}
+                }
+            }
+        }
+        if last_tick.elapsed() >= tick_rate {
+            last_tick = Instant::now();
+        }
+    }
+}
+
+fn ui(f: &mut Frame, app: &mut App) {
+    let size = f.size();
+
+    // Words made "loooong" to demonstrate line breaking.
+    let s = "Veeeeeeeeeeeeeeeery    loooooooooooooooooong   striiiiiiiiiiiiiiiiiiiiiiiiiing.   ";
+    let mut long_line = s.repeat(usize::from(size.width) / s.len() + 4);
+    long_line.push('\n');
+
+    let block = Block::default().black();
+    f.render_widget(block, size);
+
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Min(1),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+        ])
+        .split(size);
+
+    let text = vec![
+        Line::from("This is a line "),
+        Line::from("This is a line   ".red()),
+        Line::from("This is a line".on_dark_gray()),
+        Line::from("This is a longer line".crossed_out()),
+        Line::from(long_line.clone()),
+        Line::from("This is a line".reset()),
+        Line::from(vec![
+            Span::raw("Masked text: "),
+            Span::styled(
+                Masked::new("password", '*'),
+                Style::default().fg(Color::Red),
+            ),
+        ]),
+        Line::from("This is a line "),
+        Line::from("This is a line   ".red()),
+        Line::from("This is a line".on_dark_gray()),
+        Line::from("This is a longer line".crossed_out()),
+        Line::from(long_line.clone()),
+        Line::from("This is a line".reset()),
+        Line::from(vec![
+            Span::raw("Masked text: "),
+            Span::styled(
+                Masked::new("password", '*'),
+                Style::default().fg(Color::Red),
+            ),
+        ]),
+    ];
+    app.vertical_scroll_state = app.vertical_scroll_state.content_length(text.len());
+    app.horizontal_scroll_state = app.horizontal_scroll_state.content_length(long_line.len());
+
+    let create_block = |title| {
+        Block::default()
+            .borders(Borders::ALL)
+            .gray()
+            .title(Span::styled(
+                title,
+                Style::default().add_modifier(Modifier::BOLD),
+            ))
+    };
+
+    let title = Block::default()
+        .title("Use h j k l to scroll ◄ ▲ ▼ ►")
+        .title_alignment(Alignment::Center);
+    f.render_widget(title, chunks[0]);
+
+    let paragraph = Paragraph::new(text.clone())
+        .gray()
+        .block(create_block("Vertical scrollbar with arrows"))
+        .scroll((app.vertical_scroll as u16, 0));
+    f.render_widget(paragraph, chunks[1]);
+    f.render_stateful_widget(
+        Scrollbar::default()
+            .orientation(ScrollbarOrientation::VerticalRight)
+            .begin_symbol(Some("↑"))
+            .end_symbol(Some("↓")),
+        chunks[1],
+        &mut app.vertical_scroll_state,
+    );
+
+    let paragraph = Paragraph::new(text.clone())
+        .gray()
+        .block(create_block(
+            "Vertical scrollbar without arrows, without track symbol and mirrored",
+        ))
+        .scroll((app.vertical_scroll as u16, 0));
+    f.render_widget(paragraph, chunks[2]);
+    f.render_stateful_widget(
+        Scrollbar::default()
+            .orientation(ScrollbarOrientation::VerticalLeft)
+            .symbols(scrollbar::VERTICAL)
+            .begin_symbol(None)
+            .track_symbol(None)
+            .end_symbol(None),
+        chunks[2].inner(&Margin {
+            vertical: 1,
+            horizontal: 0,
+        }),
+        &mut app.vertical_scroll_state,
+    );
+
+    let paragraph = Paragraph::new(text.clone())
+        .gray()
+        .block(create_block(
+            "Horizontal scrollbar with only begin arrow & custom thumb symbol",
+        ))
+        .scroll((0, app.horizontal_scroll as u16));
+    f.render_widget(paragraph, chunks[3]);
+    f.render_stateful_widget(
+        Scrollbar::default()
+            .orientation(ScrollbarOrientation::HorizontalBottom)
+            .thumb_symbol("🬋")
+            .end_symbol(None),
+        chunks[3].inner(&Margin {
+            vertical: 0,
+            horizontal: 1,
+        }),
+        &mut app.horizontal_scroll_state,
+    );
+
+    let paragraph = Paragraph::new(text.clone())
+        .gray()
+        .block(create_block(
+            "Horizontal scrollbar without arrows & custom thumb and track symbol",
+        ))
+        .scroll((0, app.horizontal_scroll as u16));
+    f.render_widget(paragraph, chunks[4]);
+    f.render_stateful_widget(
+        Scrollbar::default()
+            .orientation(ScrollbarOrientation::HorizontalBottom)
+            .thumb_symbol("░")
+            .track_symbol(Some("─")),
+        chunks[4].inner(&Margin {
+            vertical: 0,
+            horizontal: 1,
+        }),
+        &mut app.horizontal_scroll_state,
+    );
+}
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				`<!-- Please read CONTRIBUTING.md before submitting any pull request. -->`