fix(terminal): Terminal::insert_before would crash when called while the viewport filled the screen (#1329 )

Reimplement Terminal::insert_before. The previous implementation would insert the new lines in chunks into the area between the top of the screen and the top of the (new) viewport. If the viewport filled the screen, there would be no area in which to insert lines, and the function would crash. The new implementation uses as much of the screen as it needs to, all the way up to using the whole screen. This commit: - adds a scrollback buffer to the `TestBackend` so that tests can inspect and assert the state of the scrollback buffer in addition to the screen - adds functions to `TestBackend` to assert the state of the scrollback - adds and updates `TestBackend` tests to test the behavior of the scrollback and the new asserting functions - reimplements `Terminal::insert_before`, including adding two new helper functions `Terminal::draw_lines` and `Terminal::scroll_up`. - updates the documentation for `Terminal::insert_before` to clarify some of the edge cases - updates terminal tests to assert the state of the scrollback buffer - adds a new test for the condition that causes the bug - adds a conversion constructor `Cell::from(char)` Fixes: https://github.com/ratatui/ratatui/issues/999
docs(examples): add widget implementation example (#1147 )
2024-08-23 15:27:54 -07:00 · 2024-08-23 14:30:23 -07:00 · 2024-08-22 09:14:16 -07:00 · 2024-08-22 15:16:35 +03:00 · 2024-08-21 11:35:08 -07:00 · 2024-08-17 16:17:42 -07:00
241 changed files with 66827 additions and 11247 deletions
--- 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,17 @@
+# configuration for https://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.rs]
+indent_style = space
+indent_size = 4
+
+[*.yml]
+indent_style = space
+indent_size = 2
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -0,0 +1,11 @@
+# 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
+
+* @ratatui/maintainers
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,56 @@
+---
+name: Bug report
+about: Create an issue about a bug you encountered
+title: ''
+labels: 'Type: 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,14 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Frequently Asked Questions
+    url: https://ratatui.rs/faq/
+    about: Check the website FAQ section to see if your question has already been answered
+  - name: Ratatui Forum
+    url: https://forum.ratatui.rs
+    about: Ask questions about ratatui on our Forum
+  - 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: 'Type: 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/bench_base.yml
+++ b/.github/workflows/bench_base.yml
@@ -0,0 +1,25 @@
+name: Run Benchmarks
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  benchmark_base_branch:
+    name: Continuous Benchmarking with Bencher
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - uses: bencherdev/bencher@main
+      - name: Track base branch benchmarks with Bencher
+        run: |
+          bencher run \
+          --project ratatui-org \
+          --token '${{ secrets.BENCHER_API_TOKEN }}' \
+          --branch main \
+          --testbed ubuntu-latest \
+          --adapter rust_criterion \
+          --err \
+          cargo bench
--- a/.github/workflows/bench_run_fork_pr.yml
+++ b/.github/workflows/bench_run_fork_pr.yml
@@ -0,0 +1,25 @@
+name: Run and Cache Benchmarks
+
+on:
+  pull_request:
+    types: [opened, reopened, edited, synchronize]
+
+jobs:
+  benchmark_fork_pr_branch:
+    name: Run Fork PR Benchmarks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Run Benchmarks
+        run: cargo bench > benchmark_results.txt
+      - name: Upload Benchmark Results
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark_results.txt
+          path: ./benchmark_results.txt
+      - name: Upload GitHub Pull Request Event
+        uses: actions/upload-artifact@v4
+        with:
+          name: event.json
+          path: ${{ github.event_path }}
--- a/.github/workflows/bench_track_fork_pr.yml
+++ b/.github/workflows/bench_track_fork_pr.yml
@@ -0,0 +1,75 @@
+name: Track Benchmarks with Bencher
+
+on:
+  workflow_run:
+    workflows: [Run and Cache Benchmarks]
+    types: [completed]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  track_fork_pr_branch:
+    if: github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    env:
+      BENCHMARK_RESULTS: benchmark_results.txt
+      PR_EVENT: event.json
+    steps:
+      - name: Download Benchmark Results
+        uses: actions/github-script@v7
+        with:
+          script: |
+            async function downloadArtifact(artifactName) {
+              let allArtifacts = await github.rest.actions.listWorkflowRunArtifacts({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                run_id: context.payload.workflow_run.id,
+              });
+              let matchArtifact = allArtifacts.data.artifacts.filter((artifact) => {
+                return artifact.name == artifactName
+              })[0];
+              if (!matchArtifact) {
+                core.setFailed(`Failed to find artifact: ${artifactName}`);
+              }
+              let download = await github.rest.actions.downloadArtifact({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                artifact_id: matchArtifact.id,
+                archive_format: 'zip',
+              });
+              let fs = require('fs');
+              fs.writeFileSync(`${process.env.GITHUB_WORKSPACE}/${artifactName}.zip`, Buffer.from(download.data));
+            }
+            await downloadArtifact(process.env.BENCHMARK_RESULTS);
+            await downloadArtifact(process.env.PR_EVENT);
+      - name: Unzip Benchmark Results
+        run: |
+          unzip $BENCHMARK_RESULTS.zip
+          unzip $PR_EVENT.zip
+      - name: Export PR Event Data
+        uses: actions/github-script@v7
+        with:
+          script: |
+            let fs = require('fs');
+            let prEvent = JSON.parse(fs.readFileSync(process.env.PR_EVENT, {encoding: 'utf8'}));
+            core.exportVariable("PR_HEAD", `${prEvent.number}/merge`);
+            core.exportVariable("PR_BASE", prEvent.pull_request.base.ref);
+            core.exportVariable("PR_BASE_SHA", prEvent.pull_request.base.sha);
+            core.exportVariable("PR_NUMBER", prEvent.number);
+      - uses: bencherdev/bencher@main
+      - name: Track Benchmarks with Bencher
+        run: |
+          bencher run \
+          --project ratatui-org \
+          --token '${{ secrets.BENCHER_API_TOKEN }}' \
+          --branch '${{ env.PR_HEAD }}' \
+          --branch-start-point '${{ env.PR_BASE }}' \
+          --branch-start-point-hash '${{ env.PR_BASE_SHA }}' \
+          --testbed ubuntu-latest \
+          --adapter rust_criterion \
+          --err \
+          --github-actions '${{ secrets.GITHUB_TOKEN }}' \
+          --ci-number '${{ env.PR_NUMBER }}' \
+          --file "$BENCHMARK_RESULTS"
--- a/.github/workflows/calculate-alpha-release.bash
+++ b/.github/workflows/calculate-alpha-release.bash
@@ -0,0 +1,52 @@
+#!/bin/bash
+
+# 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
+
+last_release="$(git tag --sort=committerdate | grep -P "v0+\.\d+\.\d+$" | tail -1)"
+echo "🐭 Last release: ${last_release}"
+
+# detect breaking changes
+if [ -n "$(git log --oneline ${last_release}..HEAD | grep '!:')" ]; then
+    echo "🐭 Breaking changes detected since ${last_release}"
+    git log --oneline ${last_release}..HEAD | grep '!:'
+    # increment the minor version
+    minor="${last_release##v0.}"
+    minor="${minor%.*}"
+    next_minor="$((minor + 1))"
+    next_release="v0.${next_minor}.0"
+else
+    # increment the patch version
+    patch="${last_release##*.}"
+    next_patch="$((patch + 1))"
+    next_release="${last_release/%${patch}/${next_patch}}"
+fi
+echo "🐭 Next release: ${next_release}"
+
+suffix="alpha"
+last_tag="$(git tag --sort=committerdate | tail -1)"
+if [[ "${last_tag}" = "${next_release}-${suffix}"* ]]; then
+    echo "🐭 Last alpha release: ${last_tag}"
+    # 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
+    next_tag="${next_release}-${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}"
--- a/.github/workflows/cd.yml
+++ b/.github/workflows/cd.yml
@@ -0,0 +1,66 @@
+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: .github/workflows/calculate-alpha-release.bash
+
+      - 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@v3
+        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,86 @@
+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
+    env:
+      # use an environment variable to pass untrusted input to the script
+      # see https://securitylab.github.com/research/github-actions-untrusted-input/
+      PR_TITLE: ${{ github.event.pull_request.title }}
+    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 "${PR_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@v7
+      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: ['Type: 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/check-semver.yml
+++ b/.github/workflows/check-semver.yml
@@ -0,0 +1,16 @@
+name: Check Semver
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  check-semver:
+    name: Check semver
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+      - name: Check semver
+        uses: obi1kenobi/cargo-semver-checks-action@v2
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,153 @@
+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
+
+# lint, clippy and coverage 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:
+  rustfmt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: rustfmt
+      - run: cargo +nightly fmt --all --check
+
+  typos:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: crate-ci/typos@master
+
+  dependencies:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: EmbarkStudios/cargo-deny-action@v2
+
+  clippy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: taiki-e/install-action@cargo-make
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo make clippy
+
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DavidAnson/markdownlint-cli2-action@v16
+        with:
+          globs: |
+            '**/*.md'
+            '!target'
+
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: llvm-tools
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-llvm-cov,cargo-make
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo make coverage
+      - uses: codecov/codecov-action@v4
+        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.74.0", "stable"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ matrix.toolchain }}
+      - uses: taiki-e/install-action@cargo-make
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo make check
+        env:
+          RUST_BACKTRACE: full
+
+  lint-docs:
+    runs-on: ubuntu-latest
+    env:
+      RUSTDOCFLAGS: -Dwarnings
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+      - uses: dtolnay/install@cargo-docs-rs
+      - uses: Swatinem/rust-cache@v2
+      # Run cargo rustdoc with the same options that would be used by docs.rs, taking into account
+      # the package.metadata.docs.rs configured in Cargo.toml.
+      # https://github.com/dtolnay/cargo-docs-rs
+      - run: cargo +nightly docs-rs
+
+  test-doc:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: taiki-e/install-action@cargo-make
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo make test-doc
+        env:
+          RUST_BACKTRACE: full
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        toolchain: ["1.74.0", "stable"]
+        backend: [crossterm, termion, termwiz]
+        exclude:
+          # termion is not supported on windows
+          - os: windows-latest
+            backend: termion
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ matrix.toolchain }}
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-make,nextest
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo make test-backend ${{ matrix.backend }}
+        env:
+          RUST_BACKTRACE: full
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,6 @@
 target
 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,8 +0,0 @@
-language: rust
-rust:
-  - stable
-  - beta
-  - nightly
-matrix:
-  allow_failures:
-    - rust: nightly
--- a/BREAKING-CHANGES.md
+++ b/BREAKING-CHANGES.md
@@ -0,0 +1,699 @@
+# Breaking Changes
+
+This document contains a list of breaking changes in each version and some notes to help migrate
+between versions. It is compiled manually from the commit history and changelog. We also tag PRs on
+GitHub with a [breaking change] label.
+
+[breaking change]: (https://github.com/ratatui/ratatui/issues?q=label%3A%22breaking+change%22)
+
+## Summary
+
+This is a quick summary of the sections below:
+
+- [v0.28.0](#v0280)
+  ⁻ `Backend::size` returns `Size` instead of `Rect`
+  - `Backend` trait migrates to `get/set_cursor_position`
+  - Ratatui now requires Crossterm 0.28.0
+  - `Axis::labels` now accepts `IntoIterator<Into<Line>>`
+  - `Layout::init_cache` no longer returns bool and takes a `NonZeroUsize` instead of `usize`
+  - `ratatui::terminal` module is now private
+  - `ToText` no longer has a lifetime
+  - `Frame::size` is deprecated and renamed to `Frame::area`
+- [v0.27.0](#v0270)
+  - List no clamps the selected index to list
+  - Prelude items added / removed
+  - 'termion' updated to 4.0
+  - `Rect::inner` takes `Margin` directly instead of reference
+  - `Buffer::filled` takes `Cell` directly instead of reference
+  - `Stylize::bg()` now accepts `Into<Color>`
+  - Removed deprecated `List::start_corner`
+  - `LineGauge::gauge_style` is deprecated
+- [v0.26.0](#v0260)
+  - `Flex::Start` is the new default flex mode for `Layout`
+  - `patch_style` & `reset_style` now consume and return `Self`
+  - Removed deprecated `Block::title_on_bottom`
+  - `Line` now has an extra `style` field which applies the style to the entire line
+  - `Block` style methods cannot be created in a const context
+  - `Tabs::new()` now accepts `IntoIterator<Item: Into<Line<'a>>>`
+  - `Table::new` now accepts `IntoIterator<Item: Into<Row<'a>>>`.
+- [v0.25.0](#v0250)
+  - Removed `Axis::title_style` and `Buffer::set_background`
+  - `List::new()` now accepts `IntoIterator<Item = Into<ListItem<'a>>>`
+  - `Table::new()` now requires specifying the widths
+  - `Table::widths()` now accepts `IntoIterator<Item = AsRef<Constraint>>`
+  - Layout::new() now accepts direction and constraint parameters
+  - The default `Tabs::highlight_style` is now `Style::new().reversed()`
+- [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.28.0
+
+### `Backend::size` returns `Size` instead of `Rect` ([#1254])
+
+[#1254]: https://github.com/ratatui/ratatui/pull/1254
+
+The `Backend::size` method returns a `Size` instead of a `Rect`.
+There is no need for the position here as it was always 0,0.
+
+### `Backend` trait migrates to `get/set_cursor_position` ([#1284])
+
+[#1284]: https://github.com/ratatui/ratatui/pull/1284
+
+If you just use the types implementing the `Backend` trait, you will see deprecation hints but
+nothing is a breaking change for you.
+
+If you implement the Backend trait yourself, you need to update the implementation and add the
+`get/set_cursor_position` method. You can remove the `get/set_cursor` methods as they are deprecated
+and a default implementation for them exists.
+
+### Ratatui now requires Crossterm 0.28.0 ([#1278])
+
+[#1278]: https://github.com/ratatui/ratatui/pull/1278
+
+Crossterm is updated to version 0.28.0, which is a semver incompatible version with the previous
+version (0.27.0). Ratatui re-exports the version of crossterm that it is compatible with under
+`ratatui::crossterm`, which can be used to avoid incompatible versions in your dependency list.
+
+### `Axis::labels()` now accepts `IntoIterator<Into<Line>>` ([#1273] and [#1283])
+
+[#1273]: https://github.com/ratatui/ratatui/pull/1173
+[#1283]: https://github.com/ratatui/ratatui/pull/1283
+
+Previously Axis::labels accepted `Vec<Span>`. Any code that uses conversion methods that infer the
+type will need to be rewritten as the compiler cannot infer the correct type.
+
+```diff
+- Axis::default().labels(vec!["a".into(), "b".into()])
+ Axis::default().labels(["a", "b"])
+```
+
+### `Layout::init_cache` no longer returns bool and takes a `NonZeroUsize` instead of `usize` ([#1245])
+
+[#1245]: https://github.com/ratatui/ratatui/pull/1245
+
+```diff
+- let is_initialized = Layout::init_cache(100);
+ Layout::init_cache(NonZeroUsize::new(100).unwrap());
+```
+
+### `ratatui::terminal` module is now private ([#1160])
+
+[#1160]: https://github.com/ratatui/ratatui/pull/1160
+
+The `terminal` module is now private and can not be used directly. The types under this module are
+exported from the root of the crate. This reduces clashes with other modules in the backends that
+are also named terminal, and confusion about module exports for newer Rust users.
+
+```diff
+- use ratatui::terminal::{CompletedFrame, Frame, Terminal, TerminalOptions, ViewPort};
+ use ratatui::{CompletedFrame, Frame, Terminal, TerminalOptions, ViewPort};
+```
+
+### `ToText` no longer has a lifetime ([#1234])
+
+[#1234]: https://github.com/ratatui/ratatui/pull/1234
+
+This change simplifies the trait and makes it easier to implement.
+
+### `Frame::size` is deprecated and renamed to `Frame::area`
+
+[#1293]: https://github.com/ratatui/ratatui/pull/1293
+
+`Frame::size` is renamed to `Frame::area` as it's the more correct name.
+
+## [v0.27.0](https://github.com/ratatui/ratatui/releases/tag/v0.27.0)
+
+### List no clamps the selected index to list ([#1159])
+
+[#1149]: https://github.com/ratatui/ratatui/pull/1149
+
+The `List` widget now clamps the selected index to the bounds of the list when navigating with
+`first`, `last`, `previous`, and `next`, as well as when setting the index directly with `select`.
+
+Previously selecting an index past the end of the list would show treat the list as having a
+selection which was not visible. Now the last item in the list will be selected instead.
+
+### Prelude items added / removed ([#1149])
+
+The following items have been removed from the prelude:
+
+- `style::Styled` - this trait is useful for widgets that want to
+  support the Stylize trait, but it adds complexity as widgets have two
+  `style` methods and a `set_style` method.
+- `symbols::Marker` - this item is used by code that needs to draw to
+  the `Canvas` widget, but it's not a common item that would be used by
+  most users of the library.
+- `terminal::{CompletedFrame, TerminalOptions, Viewport}` - these items
+  are rarely used by code that needs to interact with the terminal, and
+  they're generally only ever used once in any app.
+
+The following items have been added to the prelude:
+
+- `layout::{Position, Size}` - these items are used by code that needs
+  to interact with the layout system. These are newer items that were
+  added in the last few releases, which should be used more liberally.
+  This may cause conflicts for types defined elsewhere with a similar
+  name.
+
+To update your app:
+
+```diff
+// if your app uses Styled::style() or Styled::set_style():
+-use ratatui::prelude::*;
+use ratatui::{prelude::*, style::Styled};
+
+// if your app uses symbols::Marker:
+-use ratatui::prelude::*;
+use ratatui::{prelude::*, symbols::Marker}
+
+// if your app uses terminal::{CompletedFrame, TerminalOptions, Viewport}
+-use ratatui::prelude::*;
+use ratatui::{prelude::*, terminal::{CompletedFrame, TerminalOptions, Viewport}};
+
+// to disambiguate existing types named Position or Size:
+- use some_crate::{Position, Size};
+- let size: Size = ...;
+- let position: Position = ...;
+ let size: some_crate::Size = ...;
+ let position: some_crate::Position = ...;
+```
+
+### Termion is updated to 4.0 [#1106]
+
+Changelog: <https://gitlab.redox-os.org/redox-os/termion/-/blob/master/CHANGELOG.md>
+
+A change is only necessary if you were matching on all variants of the `MouseEvent` enum without a
+wildcard. In this case, you need to either handle the two new variants, `MouseLeft` and
+`MouseRight`, or add a wildcard.
+
+[#1106]: https://github.com/ratatui/ratatui/pull/1106
+
+### `Rect::inner` takes `Margin` directly instead of reference ([#1008])
+
+[#1008]: https://github.com/ratatui/ratatui/pull/1008
+
+`Margin` needs to be passed without reference now.
+
+```diff
+-let area = area.inner(&Margin {
+let area = area.inner(Margin {
+     vertical: 0,
+     horizontal: 2,
+ });
+```
+
+### `Buffer::filled` takes `Cell` directly instead of reference ([#1148])
+
+[#1148]: https://github.com/ratatui/ratatui/pull/1148
+
+`Buffer::filled` moves the `Cell` instead of taking a reference.
+
+```diff
+-Buffer::filled(area, &Cell::new("X"));
+Buffer::filled(area, Cell::new("X"));
+```
+
+### `Stylize::bg()` now accepts `Into<Color>` ([#1103])
+
+[#1103]: https://github.com/ratatui/ratatui/pull/1103
+
+Previously, `Stylize::bg()` accepted `Color` but now accepts `Into<Color>`. This allows more
+flexible types from calling scopes, though it can break some type inference in the calling scope.
+
+### Remove deprecated `List::start_corner` and `layout::Corner` ([#759])
+
+[#759]: https://github.com/ratatui/ratatui/pull/759
+
+`List::start_corner` was deprecated in v0.25. Use `List::direction` and `ListDirection` instead.
+
+```diff
+- list.start_corner(Corner::TopLeft);
+- list.start_corner(Corner::TopRight);
+// This is not an error, BottomRight rendered top to bottom previously
+- list.start_corner(Corner::BottomRight);
+// all becomes
+ list.direction(ListDirection::TopToBottom);
+```
+
+```diff
+- list.start_corner(Corner::BottomLeft);
+// becomes
+ list.direction(ListDirection::BottomToTop);
+```
+
+`layout::Corner` was removed entirely.
+
+### `LineGauge::gauge_style` is deprecated ([#565])
+
+[#565]: https://github.com/ratatui/ratatui/pull/1148
+
+`LineGauge::gauge_style` is deprecated and replaced with `LineGauge::filled_style` and `LineGauge::unfilled_style`:
+
+```diff
+let gauge = LineGauge::default()
+- .gauge_style(Style::default().fg(Color::Red).bg(Color::Blue)
+ .filled_style(Style::default().fg(Color::Green))
+ .unfilled_style(Style::default().fg(Color::White));
+```
+
+## [v0.26.0](https://github.com/ratatui/ratatui/releases/tag/v0.26.0)
+
+### `Flex::Start` is the new default flex mode for `Layout` ([#881])
+
+[#881]: https://github.com/ratatui/ratatui/pull/881
+
+Previously, constraints would stretch to fill all available space, violating constraints if
+necessary.
+
+With v0.26.0, `Flex` modes are introduced, and the default is `Flex::Start`, which will align
+areas associated with constraints to be beginning of the area. With v0.26.0, additionally,
+`Min` constraints grow to fill excess space. These changes will allow users to build layouts
+more easily.
+
+With v0.26.0, users will most likely not need to change what constraints they use to create
+existing layouts with `Flex::Start`. However, to get old behavior, use `Flex::Legacy`.
+
+```diff
+- let rects = Layout::horizontal([Length(1), Length(2)]).split(area);
+// becomes
+ let rects = Layout::horizontal([Length(1), Length(2)]).flex(Flex::Legacy).split(area);
+```
+
+### `Table::new()` now accepts `IntoIterator<Item: Into<Row<'a>>>` ([#774])
+
+[#774]: https://github.com/ratatui/ratatui/pull/774
+
+Previously, `Table::new()` accepted `IntoIterator<Item=Row<'a>>`. The argument change to
+`IntoIterator<Item: Into<Row<'a>>>`, This allows more flexible types from calling scopes, though it
+can some break type inference in the calling scope for empty containers.
+
+This can be resolved either by providing an explicit type (e.g. `Vec::<Row>::new()`), or by using
+`Table::default()`.
+
+```diff
+- let table = Table::new(vec![], widths);
+// becomes
+ let table = Table::default().widths(widths);
+```
+
+### `Tabs::new()` now accepts `IntoIterator<Item: Into<Line<'a>>>` ([#776])
+
+[#776]: https://github.com/ratatui/ratatui/pull/776
+
+Previously, `Tabs::new()` accepted `Vec<T>` where `T: Into<Line<'a>>`. This allows more flexible
+types from calling scopes, though it can break some type inference in the calling scope.
+
+This typically occurs when collecting an iterator prior to calling `Tabs::new`, and can be resolved
+by removing the call to `.collect()`.
+
+```diff
+- let tabs = Tabs::new((0.3).map(|i| format!("{i}")).collect());
+// becomes
+ let tabs = Tabs::new((0.3).map(|i| format!("{i}")));
+```
+
+### Table::default() now sets segment_size to None and column_spacing to ([#751])
+
+[#751]: https://github.com/ratatui/ratatui/pull/751
+
+The default() implementation of Table now sets the column_spacing field to 1 and the segment_size
+field to `SegmentSize::None`. This will affect the rendering of a small amount of apps.
+
+To use the previous default values, call `table.segment_size(Default::default())` and
+`table.column_spacing(0)`.
+
+### `patch_style` & `reset_style` now consumes and returns `Self` ([#754])
+
+[#754]: https://github.com/ratatui/ratatui/pull/754
+
+Previously, `patch_style` and `reset_style` in `Text`, `Line` and `Span` were using a mutable
+reference to `Self`. To be more consistent with the rest of `ratatui`, which is using fluent
+setters, these now take ownership of `Self` and return it.
+
+The following example shows how to migrate for `Line`, but the same applies for `Text` and `Span`.
+
+```diff
+- let mut line = Line::from("foobar");
+- line.patch_style(style);
+// becomes
+ let line = Line::new("foobar").patch_style(style);
+```
+
+### Remove deprecated `Block::title_on_bottom` ([#757])
+
+`Block::title_on_bottom` was deprecated in v0.22. Use `Block::title` and `Title::position` instead.
+
+```diff
+- block.title("foobar").title_on_bottom();
+ block.title(Title::from("foobar").position(Position::Bottom));
+```
+
+### `Block` style methods cannot be used in a const context ([#720])
+
+[#720]: https://github.com/ratatui/ratatui/pull/720
+
+Previously the `style()`, `border_style()` and `title_style()` methods could be used to create a
+`Block` in a constant context. These now accept `Into<Style>` instead of `Style`. These methods no
+longer can be called from a constant context.
+
+### `Line` now has a `style` field that applies to the entire line ([#708])
+
+[#708]: https://github.com/ratatui/ratatui/pull/708
+
+Previously the style of a `Line` was stored in the `Span`s that make up the line. Now the `Line`
+itself has a `style` field, which can be set with the `Line::styled` method. Any code that creates
+`Line`s using the struct initializer instead of constructors will fail to compile due to the added
+field. This can be easily fixed by adding `..Default::default()` to the field list or by using a
+constructor method (`Line::styled()`, `Line::raw()`) or conversion method (`Line::from()`).
+
+Each `Span` contained within the line will no longer have the style that is applied to the line in
+the `Span::style` field.
+
+```diff
+  let line = Line {
+      spans: vec!["".into()],
+      alignment: Alignment::Left,
+     ..Default::default()
+  };
+
+  // or
+
+  let line = Line::raw(vec!["".into()])
+      .alignment(Alignment::Left);
+```
+
+## [v0.25.0](https://github.com/ratatui/ratatui/releases/tag/v0.25.0)
+
+### Removed `Axis::title_style` and `Buffer::set_background` ([#691])
+
+[#691]: https://github.com/ratatui/ratatui/pull/691
+
+These items were deprecated since 0.10.
+
+- You should use styling capabilities of [`text::Line`] given as argument of [`Axis::title`]
+  instead of `Axis::title_style`
+- You should use styling capabilities of [`Buffer::set_style`] instead of `Buffer::set_background`
+
+[`text::Line`]: https://docs.rs/ratatui/latest/ratatui/text/struct.Line.html
+[`Axis::title`]: https://docs.rs/ratatui/latest/ratatui/widgets/struct.Axis.html#method.title
+[`Buffer::set_style`]: https://docs.rs/ratatui/latest/ratatui/buffer/struct.Buffer.html#method.set_style
+
+### `List::new()` now accepts `IntoIterator<Item = Into<ListItem<'a>>>` ([#672])
+
+[#672]: https://github.com/ratatui/ratatui/pull/672
+
+Previously `List::new()` took `Into<Vec<ListItem<'a>>>`. This change will throw a compilation
+error for `IntoIterator`s with an indeterminate item (e.g. empty vecs).
+
+E.g.
+
+```diff
+- let list = List::new(vec![]);
+// becomes
+ let list = List::default();
+```
+
+### The default `Tabs::highlight_style` is now `Style::new().reversed()` ([#635])
+
+[#635]: https://github.com/ratatui/ratatui/pull/635
+
+Previously the default highlight style for tabs was `Style::default()`, which meant that a `Tabs`
+widget in the default configuration would not show any indication of the selected tab.
+
+### The default `Tabs::highlight_style` is now `Style::new().reversed()` ([#635])
+
+Previously the default highlight style for tabs was `Style::default()`, which meant that a `Tabs`
+widget in the default configuration would not show any indication of the selected tab.
+
+### `Table::new()` now requires specifying the widths of the columns ([#664])
+
+[#664]: https://github.com/ratatui/ratatui/pull/664
+
+Previously `Table`s could be constructed without `widths`. In almost all cases this is an error.
+A new `widths` parameter is now mandatory on `Table::new()`. Existing code of the form:
+
+```diff
+- Table::new(rows).widths(widths)
+```
+
+Should be updated to:
+
+```diff
+ Table::new(rows, widths)
+```
+
+For ease of automated replacement in cases where the amount of code broken by this change is large
+or complex, it may be convenient to replace `Table::new` with `Table::default().rows`.
+
+```diff
+- Table::new(rows).block(block).widths(widths);
+// becomes
+ Table::default().rows(rows).widths(widths)
+```
+
+### `Table::widths()` now accepts `IntoIterator<Item = AsRef<Constraint>>` ([#663])
+
+[#663]: https://github.com/ratatui/ratatui/pull/663
+
+Previously `Table::widths()` took a slice (`&'a [Constraint]`). This change will introduce clippy
+`needless_borrow` warnings for places where slices are passed to this method. To fix these, remove
+the `&`.
+
+E.g.
+
+```diff
+- let table = Table::new(rows).widths(&[Constraint::Length(1)]);
+// becomes
+ let table = Table::new(rows, [Constraint::Length(1)]);
+```
+
+### Layout::new() now accepts direction and constraint parameters ([#557])
+
+[#557]: https://github.com/ratatui/ratatui/pull/557
+
+Previously layout new took no parameters. Existing code should either use `Layout::default()` or
+the new constructor.
+
+```rust
+let layout = layout::new()
+  .direction(Direction::Vertical)
+  .constraints([Constraint::Min(1), Constraint::Max(2)]);
+// becomes either
+let layout = layout::default()
+  .direction(Direction::Vertical)
+  .constraints([Constraint::Min(1), Constraint::Max(2)]);
+// or
+let layout = layout::new(Direction::Vertical, [Constraint::Min(1), Constraint::Max(2)]);
+```
+
+## [v0.24.0](https://github.com/ratatui/ratatui/releases/tag/v0.24.0)
+
+### `ScrollbarState` field type changed from `u16` to `usize` ([#456])
+
+[#456]: https://github.com/ratatui/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/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.:
+
+```diff
+- 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/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.:
+
+```diff
+- 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/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.
+
+```diff
+- 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/ratatui/issues/426
+
+`Spans` was replaced with `Line` in 0.21.0. `Buffer::set_spans` was replaced with
+`Buffer::set_line`.
+
+```diff
+- 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/ratatui/releases/tag/v0.23.0)
+
+### `Scrollbar::track_symbol()` now takes an `Option<&str>` instead of `&str` ([#360])
+
+[#360]: https://github.com/ratatui/ratatui/issues/360
+
+The track symbol of `Scrollbar` is now optional, this method now takes an optional value.
+
+```diff
+- 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/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.:
+
+```diff
+- 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/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/ratatui/releases/tag/v0.22.0)
+
+### `bitflags` updated to 2.3 ([#205])
+
+[#205]: https://github.com/ratatui/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/ratatui/releases/tag/v0.21.0)
+
+### MSRV is 1.65.0 ([#171])
+
+[#171]: https://github.com/ratatui/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/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.
+
+```diff
+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/ratatui/issues/168
+
+A new type `Masked` was introduced that implements `From<Text<'a>>`. This causes any code that
+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.:
+
+```diff
+- 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/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.
+
+```diff
+- let canvas = Canvas::default().marker(Marker::Block);
+// becomes
+ let canvas = Canvas::default().marker(Marker::Bar);
+```
+
+## [v0.20.0](https://github.com/ratatui/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/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/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/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+https://forum.ratatui.rs/ or https://discord.gg/pMCEU9hNEj.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,211 @@
+# 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/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.
+
+### Run CI tests before pushing a PR
+
+Running `cargo make ci` before pushing will perform the same checks that we do in the CI process.
+It's not mandatory to do this before pushing, however it may save you time to do so instead of
+waiting for GitHub to run the checks.
+
+### 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/ratatui.git
+cd ratatui
+cargo make build
+```
+
+### Tests
+
+The [test coverage](https://app.codecov.io/gh/ratatui/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 [VS Code 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]``
+
+### Deprecation notice
+
+We generally want to wait at least two versions before removing deprecated items, so users have
+time to update. However, if a deprecation is blocking for us to implement a new feature we may
+*consider* removing it in a one version notice.
+
+### 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/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, 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/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,27 +1,375 @@
 [package]
-name = "tui"
-version = "0.1.2"
-authors = ["Florian Dehau <work@fdehau.com>"]
-description = """
-A library to build rich terminal user interfaces or dashboards
-"""
+name = "ratatui"
+version = "0.28.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/"
+repository = "https://github.com/ratatui/ratatui"
+homepage = "https://ratatui.rs"
 keywords = ["tui", "terminal", "dashboard"]
-repository = "https://github.com/fdehau/tui-rs"
+categories = ["command-line-interface"]
+readme = "README.md"
 license = "MIT"
-exclude = ["docs", ".travis.yml"]
-
-[features]
-default = ["rustbox", "termion"]
+exclude = [
+  "assets/*",
+  ".github",
+  "Makefile.toml",
+  "CONTRIBUTING.md",
+  "*.log",
+  "tags",
+]
+edition = "2021"
+rust-version = "1.74.0"

 [dependencies]
-bitflags = "0.7.0"
-cassowary = "0.2.0"
-log = "0.3.6"
-unicode-segmentation = "0.1.3"
-unicode-width = "0.1.4"
-termion = { version = "1.1.4", optional = true }
-rustbox = { version = "0.9.0", optional = true }
+bitflags = "2.3"
+cassowary = "0.3"
+compact_str = "0.8.0"
+crossterm = { version = "0.28.1", optional = true }
+document-features = { version = "0.2.7", optional = true }
+instability = "0.3.1"
+itertools = "0.13"
+lru = "0.12.0"
+paste = "1.0.2"
+palette = { version = "0.7.6", optional = true }
+serde = { version = "1", optional = true, features = ["derive"] }
+strum = { version = "0.26", features = ["derive"] }
+strum_macros = { version = "0.26.3" }
+termwiz = { version = "0.22.0", optional = true }
+time = { version = "0.3.11", optional = true, features = ["local-offset"] }
+unicode-segmentation = "1.10"
+unicode-truncate = "1"
+unicode-width = "0.1.13"
+
+[target.'cfg(not(windows))'.dependencies]
+# termion is not supported on Windows
+termion = { version = "4.0.0", optional = true }

 [dev-dependencies]
-log4rs = "0.5.2"
-rand = "0.3.15"
+argh = "0.1.12"
+color-eyre = "0.6.2"
+criterion = { version = "0.5.1", features = ["html_reports"] }
+crossterm = { version = "0.28.1", features = ["event-stream"] }
+derive_builder = "0.20.0"
+fakeit = "1.1"
+font8x8 = "0.3.1"
+futures = "0.3.30"
+indoc = "2"
+octocrab = "0.39.0"
+pretty_assertions = "1.4.0"
+rand = "0.8.5"
+rand_chacha = "0.3.1"
+rstest = "0.22.0"
+serde_json = "1.0.109"
+tokio = { version = "1.39.2", features = [
+  "rt",
+  "macros",
+  "time",
+  "rt-multi-thread",
+] }
+tracing = "0.1.40"
+tracing-appender = "0.2.3"
+tracing-subscriber = { version = "0.3.18", features = ["env-filter"] }
+
+[lints.rust]
+unsafe_code = "forbid"
+
+[lints.clippy]
+cargo = { level = "warn", priority = -1 }
+pedantic = { level = "warn", priority = -1 }
+cast_possible_truncation = "allow"
+cast_possible_wrap = "allow"
+cast_precision_loss = "allow"
+cast_sign_loss = "allow"
+missing_errors_doc = "allow"
+missing_panics_doc = "allow"
+module_name_repetitions = "allow"
+must_use_candidate = "allow"
+
+# we often split up a module into multiple files with the main type in a file named after the
+# module, so we want to allow this pattern
+module_inception = "allow"
+
+# nursery or restricted
+as_underscore = "warn"
+deref_by_slicing = "warn"
+else_if_without_else = "warn"
+empty_line_after_doc_comments = "warn"
+equatable_if_let = "warn"
+fn_to_numeric_cast_any = "warn"
+format_push_string = "warn"
+map_err_ignore = "warn"
+missing_const_for_fn = "warn"
+mixed_read_write_in_expression = "warn"
+mod_module_files = "warn"
+needless_pass_by_ref_mut = "warn"
+needless_raw_strings = "warn"
+or_fun_call = "warn"
+redundant_type_annotations = "warn"
+rest_pat_in_fully_bound_structs = "warn"
+string_lit_chars_any = "warn"
+string_slice = "warn"
+string_to_string = "warn"
+unnecessary_self_imports = "warn"
+use_self = "warn"
+
+[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::CrosstermBackend) backend and adds a dependency on [`crossterm`].
+crossterm = ["dep:crossterm"]
+## enables the [`TermionBackend`](backend::TermionBackend) backend and adds a dependency on [`termion`].
+termion = ["dep:termion"]
+## enables the [`TermwizBackend`](backend::TermwizBackend) backend and adds a dependency on [`termwiz`].
+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", "compact_str/serde"]
+
+## enables the [`border!`] macro.
+macros = []
+
+## enables conversions from colors in the [`palette`] crate to [`Color`](crate::style::Color).
+palette = ["dep:palette"]
+
+## 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`](widgets::calendar) widget module and adds a dependency on [`time`].
+widget-calendar = ["dep:time"]
+
+#! The following optional features are only available for some backends:
+
+## enables the backend code that sets the underline color.
+## Underline color is only supported by the [`CrosstermBackend`](backend::CrosstermBackend) backend,
+## and is not supported on Windows 7.
+underline-color = ["dep:crossterm"]
+
+#! The following features are unstable and may change in the future:
+
+## Enable all unstable features.
+unstable = ["unstable-rendered-line-info", "unstable-widget-ref"]
+
+## Enables the [`Paragraph::line_count`](widgets::Paragraph::line_count)
+## [`Paragraph::line_width`](widgets::Paragraph::line_width) methods
+## which are experimental and may change in the future.
+## See [Issue 293](https://github.com/ratatui/ratatui/issues/293) for more details.
+unstable-rendered-line-info = []
+
+## Enables the [`WidgetRef`](widgets::WidgetRef) and [`StatefulWidgetRef`](widgets::StatefulWidgetRef) traits which are experimental and may change in
+## the future.
+unstable-widget-ref = []
+
+[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"]
+
+# Improve benchmark consistency
+[profile.bench]
+codegen-units = 1
+lto = true
+
+[lib]
+bench = false
+
+[[bench]]
+name = "main"
+harness = false
+
+[[example]]
+name = "async"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "barchart"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "barchart-grouped"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "block"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "calendar"
+required-features = ["crossterm", "widget-calendar"]
+doc-scrape-examples = true
+
+[[example]]
+name = "canvas"
+required-features = ["crossterm"]
+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", "palette"]
+doc-scrape-examples = true
+
+[[example]]
+name = "constraint-explorer"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "constraints"
+required-features = ["crossterm"]
+doc-scrape-examples = false
+
+[[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", "palette", "widget-calendar"]
+doc-scrape-examples = true
+
+[[example]]
+name = "docsrs"
+required-features = ["crossterm"]
+doc-scrape-examples = false
+
+[[example]]
+name = "flex"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "gauge"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "hello_world"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "inline"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "layout"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "line_gauge"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "hyperlink"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "list"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "minimal"
+required-features = ["crossterm"]
+# prefer to show the more featureful examples in the docs
+doc-scrape-examples = false
+
+[[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 = "ratatui-logo"
+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 = "tracing"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "user_input"
+required-features = ["crossterm"]
+doc-scrape-examples = true
+
+[[example]]
+name = "widget_impl"
+required-features = ["crossterm", "unstable-widget-ref"]
+doc-scrape-examples = true
+
+[[test]]
+name = "state_serde"
+required-features = ["serde"]
--- a/FUNDING.json
+++ b/FUNDING.json
@@ -0,0 +1,7 @@
+{
+  "drips": {
+    "ethereum": {
+      "ownedBy": "0x6053C8984f4F214Ad12c4653F28514E1E09213B5"
+    }
+  }
+}
--- 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-2024 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/MAINTAINERS.md
+++ b/MAINTAINERS.md
@@ -0,0 +1,15 @@
+# Maintainers
+
+This file documents current and past maintainers.
+
+- [orhun](https://github.com/orhun)
+- [joshka](https://github.com/joshka)
+- [kdheepak](https://github.com/kdheepak)
+- [Valentin271](https://github.com/Valentin271)
+
+## Past Maintainers
+
+- [fdehau](https://github.com/fdehau)
+- [mindoodoo](https://github.com/mindoodoo)
+- [sayanarijit](https://github.com/sayanarijit)
+- [EdJoPaTo](https://github.com/EdJoPaTo)
--- a/16
+++ b/16
@@ -1,16 +0,0 @@
-build:
-	cargo build
-test:
-	cargo test
-doc:
-	cargo doc
-clippy:
-	rustup run nightly cargo clippy
-watch:
-	watchman-make -p 'src/**/*.rs' -t build -p 'test/**/*.rs' -t test
-
-watch-test:
-	watchman-make -p 'src/**/*.rs' 'tests/**/*.rs' 'examples/**/*.rs' -t test
-
-watch-doc:
-	watchman-make -p 'src/**/*.rs' -t doc
--- a/Makefile.toml
+++ b/Makefile.toml
@@ -0,0 +1,154 @@
+# configuration for https://github.com/sagiegurari/cargo-make
+
+[config]
+skip_core_tasks = true
+
+[env]
+# all features except the backend ones
+NON_BACKEND_FEATURES = "all-widgets,macros,serde"
+
+[tasks.default]
+alias = "ci"
+
+[tasks.ci]
+description = "Run continuous integration tasks"
+dependencies = ["lint", "clippy", "check", "test"]
+
+[tasks.lint]
+description = "Lint code style (formatting, typos, docs, markdown)"
+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",
+  "--all-features",
+  "--",
+  "-Zunstable-options",
+  "--check",
+  "-Dwarnings",
+]
+
+[tasks.lint-markdown]
+description = "Check markdown files for errors and warnings"
+command = "markdownlint-cli2"
+args = ["**/*.md", "!target"]
+
+[tasks.check]
+description = "Check code for errors and warnings"
+command = "cargo"
+args = ["check", "--all-targets", "--all-features"]
+
+[tasks.build]
+description = "Compile the project"
+command = "cargo"
+args = ["build", "--all-targets", "--all-features"]
+
+[tasks.clippy]
+description = "Run Clippy for linting"
+command = "cargo"
+args = [
+  "clippy",
+  "--all-targets",
+  "--all-features",
+  "--tests",
+  "--benches",
+  "--",
+  "-D",
+  "warnings",
+]
+
+[tasks.install-nextest]
+description = "Install cargo-nextest"
+install_crate = { crate_name = "cargo-nextest", binary = "cargo-nextest", test_arg = "--help" }
+
+[tasks.test]
+description = "Run tests"
+run_task = { name = ["test-lib", "test-doc"] }
+
+[tasks.test-lib]
+description = "Run default tests"
+dependencies = ["install-nextest"]
+command = "cargo"
+args = ["nextest", "run", "--all-targets", "--all-features"]
+
+[tasks.test-doc]
+description = "Run documentation tests"
+command = "cargo"
+args = ["test", "--doc", "--all-features"]
+
+[tasks.test-backend]
+# takes a command line parameter to specify the backend to test (e.g. "crossterm")
+description = "Run backend-specific tests"
+dependencies = ["install-nextest"]
+command = "cargo"
+args = [
+  "nextest",
+  "run",
+  "--all-targets",
+  "--no-default-features",
+  "--features",
+  "${NON_BACKEND_FEATURES},${@}",
+]
+
+[tasks.coverage]
+description = "Generate code coverage report"
+command = "cargo"
+args = [
+  "llvm-cov",
+  "--lcov",
+  "--output-path",
+  "target/lcov.info",
+  "--all-features",
+]
+
+[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,153 +1,429 @@
-# 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)
-<img src="https://img.shields.io/crates/v/tui.svg" alt="tui’s current version badge" title="tui’s current version badge">
-<img src="./docs/demo.gif" alt="Demo cast under Linux Termite with Inconsolata font 12pt">
+- [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)

-`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).
+</details>

-The library itself supports two different backends to draw to the terminal. You
-can either choose from:
+<!-- cargo-rdme start -->

-  - [termion](https://github.com/ticki/termion)
-  - [rustbox](https://github.com/gchp/rustbox)
+![Demo](https://github.com/ratatui/ratatui/blob/87ae72dbc756067c97f6400d3e2a58eeb383776e/examples/demo2-destroy.gif?raw=true)

-However, some features may only be available in one of the two.
+<div align="center">

-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.
+[![Crate Badge]][Crate] [![Docs Badge]][API Docs] [![CI Badge]][CI Workflow] [![Deps.rs
+Badge]][Deps.rs]<br> [![Codecov Badge]][Codecov] [![License Badge]](./LICENSE) [![Sponsors
+Badge]][GitHub Sponsors]<br> [![Discord Badge]][Discord Server] [![Matrix Badge]][Matrix]
+[![Forum Badge]][Forum]<br>

-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 Website] · [API Docs] · [Examples] · [Changelog] · [Breaking Changes]<br>
+[Contributing] · [Report a bug] · [Request a Feature] · [Create a Pull Request]

-## Cargo.toml
+</div>

-```toml
-[dependencies]
-tui = "0.1.1"
+# Ratatui
+
+[Ratatui][Ratatui Website] 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.
+
+## Installation
+
+Add `ratatui` as a dependency to your cargo.toml:
+
+```shell
+cargo add ratatui
 ```

-## Get Started
+Ratatui uses [Crossterm] by default as it works on most platforms. See the [Installation]
+section of the [Ratatui Website] for more details on how to use other backends ([Termion] /
+[Termwiz]).

-### Create the terminal interface
+## Introduction

-The first thing to do is to choose from one of the two backends:
+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 Website]
+for more info.

-For Termion:
+You can also watch the [FOSDEM 2024 talk] about Ratatui which gives a brief introduction to
+terminal user interfaces and showcases the features of Ratatui, along with a hello world demo.
+
+## Other documentation
+
+- [Ratatui Website] - explains the library's concepts and provides step-by-step tutorials
+- [Ratatui Forum][Forum] - a place to ask questions and discuss the library
+- [API Docs] - the full API documentation for the library on docs.rs.
+- [Examples] - a collection of examples that demonstrate how to use the library.
+- [Contributing] - Please read this if you are interested in contributing to the project.
+- [Changelog] - generated by [git-cliff] utilizing [Conventional Commits].
+- [Breaking Changes] - a list of breaking changes in the library.
+
+## Quickstart
+
+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
+the [Examples] directory. For more guidance on different ways to structure your application see
+the [Application Patterns] and [Hello World tutorial] sections in the [Ratatui Website] and the
+various [Examples]. There are also several starter templates available in the [templates]
+repository.
+
+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 Website] 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. After this closure returns, a diff is performed and
+only the changes are drawn to the terminal. See the [Widgets] section of the [Ratatui Website]
+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
+Website] for more info. For example, if you are using [Crossterm], you can use the
+[`crossterm::event`] module to handle events.
+
+### Example

 ```rust
-use tui::Terminal;
-use tui::backend::TermionBackend;
+use std::io::{self, stdout};

-fn main() {
-  let backend = TermionBackend::new().unwrap();
-  let mut terminal = Terminal::new(backend);
+use ratatui::{
+    backend::CrosstermBackend,
+    crossterm::{
+        event::{self, Event, KeyCode},
+        terminal::{
+            disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen,
+        },
+        ExecutableCommand,
+    },
+    widgets::{Block, Paragraph},
+    Frame, Terminal,
+};
+
+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::bordered().title("Greeting")),
+        frame.size(),
+    );
 }
 ```

-For Rustbox:
+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 Website] for more info.

 ```rust
-use tui::Terminal;
-use tui::backend::RustboxBackend;
+use ratatui::{
+    layout::{Constraint, Layout},
+    widgets::Block,
+    Frame,
+};

-fn main() {
-  let backend = RustboxBackend::new().unwrap();
-  let mut terminal = Terminal::new(backend);
+fn ui(frame: &mut Frame) {
+    let [title_area, main_area, status_area] = Layout::vertical([
+        Constraint::Length(1),
+        Constraint::Min(0),
+        Constraint::Length(1),
+    ])
+    .areas(frame.size());
+    let [left_area, right_area] =
+        Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)])
+            .areas(main_area);
+
+    frame.render_widget(Block::bordered().title("Title Bar"), title_area);
+    frame.render_widget(Block::bordered().title("Status Bar"), status_area);
+    frame.render_widget(Block::bordered().title("Left"), left_area);
+    frame.render_widget(Block::bordered().title("Right"), right_area);
 }
 ```

-By default both backends are enabled but you might want to use only one. To do
-so, you should disable the default-features for this library and specify the
-chosen backend in features.
+Running this example produces the following output:

-```toml
-[dependencies.tui]
-version = "0.1.1"
-default-features = false
-features = ['termion']
-```
+![docsrs-layout]

-### Layout
+## Text and styling

-The library comes with a basic yet useful layout management object called
-`Group`. As you may see below and in the examples, the library makes heavy use
-of the builder pattern to provide full customization. And the `Group` object is
-no exception:
+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 Website] for more info.

 ```rust
-use tui::widgets::{Block, border};
-use tui::layout::{Group, Rect, Direction};
+use ratatui::{
+    layout::{Constraint, Layout},
+    style::{Color, Modifier, Style, Stylize},
+    text::{Line, Span},
+    widgets::{Block, Paragraph},
+    Frame,
+};

-fn draw(t: &mut Terminal<TermionBackend>) {
+fn ui(frame: &mut Frame) {
+    let areas = Layout::vertical([Constraint::Length(1); 4]).split(frame.size());

-  let size = t.size().unwrap();
+    let line = Line::from(vec![
+        Span::raw("Hello "),
+        Span::styled(
+            "World",
+            Style::new()
+                .fg(Color::Green)
+                .bg(Color::White)
+                .add_modifier(Modifier::BOLD),
+        ),
+        "!".red().on_light_yellow().italic(),
+    ]);
+    frame.render_widget(line, areas[0]);

-  Group::default()
-    /// You first choose a main direction for the group
-    .direction(Direction::Vertical)
-    /// An optional margin
-    .margin(1)
-    /// The preferred sizes (heights in this case)
-    .sizes(&[Size::Fixed(10), Size::Max(20), Size::Min(10)])
-    /// The computed (or cached) layout is then available as the second argument
-    /// of the closure
-    .render(t, &size, |t, chunks| {
-        /// Continue to describe your UI there.
-        Block::default()
-          .title("Block")
-          .borders(border::ALL)
-          .render(t, &chunks[0]);
-    })
+    // using the short-hand syntax and implicit conversions
+    let paragraph = Paragraph::new("Hello World!".red().on_white().bold());
+    frame.render_widget(paragraph, areas[1]);
+
+    // style the whole widget instead of just the text
+    let paragraph = Paragraph::new("Hello World!").style(Style::new().red().on_white());
+    frame.render_widget(paragraph, areas[2]);
+
+    // use the simpler short-hand syntax
+    let paragraph = Paragraph::new("Hello World!").blue().on_yellow();
+    frame.render_widget(paragraph, areas[3]);
+}
 ```

-This let you describe responsive terminal UI by nesting groups. You should note
-that by default the computed layout tries to fill the available space
-completely. So if for any reason you might need a blank space somewhere, try to
-pass an additional size to the group and don't use the corresponding area inside
-the render method.
+Running this example produces the following output:

-Once you have finished to describe the UI, you just need to call:
+![docsrs-styling]

-```rust
-t.draw().unwrap()
-```
+[Ratatui Website]: https://ratatui.rs/
+[Installation]: https://ratatui.rs/installation/
+[Rendering]: https://ratatui.rs/concepts/rendering/
+[Application Patterns]: https://ratatui.rs/concepts/application-patterns/
+[Hello World tutorial]: https://ratatui.rs/tutorials/hello-world/
+[Backends]: https://ratatui.rs/concepts/backends/
+[Widgets]: https://ratatui.rs/how-to/widgets/
+[Handling Events]: https://ratatui.rs/concepts/event-handling/
+[Layout]: https://ratatui.rs/how-to/layout/
+[Styling Text]: https://ratatui.rs/how-to/render/style-text/
+[templates]: https://github.com/ratatui/templates/
+[Examples]: https://github.com/ratatui/ratatui/tree/main/examples/README.md
+[Report a bug]: https://github.com/ratatui/ratatui/issues/new?labels=bug&projects=&template=bug_report.md
+[Request a Feature]: https://github.com/ratatui/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md
+[Create a Pull Request]: https://github.com/ratatui/ratatui/compare
+[git-cliff]: https://git-cliff.org
+[Conventional Commits]: https://www.conventionalcommits.org
+[API Docs]: https://docs.rs/ratatui
+[Changelog]: https://github.com/ratatui/ratatui/blob/main/CHANGELOG.md
+[Contributing]: https://github.com/ratatui/ratatui/blob/main/CONTRIBUTING.md
+[Breaking Changes]: https://github.com/ratatui/ratatui/blob/main/BREAKING-CHANGES.md
+[FOSDEM 2024 talk]: https://www.youtube.com/watch?v=NU0q6NOLJ20
+[docsrs-hello]: https://github.com/ratatui/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-hello.png?raw=true
+[docsrs-layout]: https://github.com/ratatui/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-layout.png?raw=true
+[docsrs-styling]: https://github.com/ratatui/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
+[Crate]: https://crates.io/crates/ratatui
+[Crossterm]: https://crates.io/crates/crossterm
+[Termion]: https://crates.io/crates/termion
+[Termwiz]: https://crates.io/crates/termwiz
+[tui-rs]: https://crates.io/crates/tui
+[GitHub Sponsors]: https://github.com/sponsors/ratatui
+[Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square&logoColor=E05D44&color=E05D44
+[License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square&color=1370D3
+[CI Badge]: https://img.shields.io/github/actions/workflow/status/ratatui/ratatui/ci.yml?style=flat-square&logo=github
+[CI Workflow]: https://github.com/ratatui/ratatui/actions/workflows/ci.yml
+[Codecov Badge]: https://img.shields.io/codecov/c/github/ratatui/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST&color=C43AC3&logoColor=C43AC3
+[Codecov]: https://app.codecov.io/gh/ratatui/ratatui
+[Deps.rs Badge]: https://deps.rs/repo/github/ratatui/ratatui/status.svg?style=flat-square
+[Deps.rs]: https://deps.rs/repo/github/ratatui/ratatui
+[Discord Badge]: https://img.shields.io/discord/1070692720437383208?label=discord&logo=discord&style=flat-square&color=1370D3&logoColor=1370D3
+[Discord Server]: https://discord.gg/pMCEU9hNEj
+[Docs Badge]: https://img.shields.io/docsrs/ratatui?logo=rust&style=flat-square&logoColor=E05D44
+[Matrix Badge]: https://img.shields.io/matrix/ratatui-general%3Amatrix.org?style=flat-square&logo=matrix&label=Matrix&color=C43AC3
+[Matrix]: https://matrix.to/#/#ratatui:matrix.org
+[Forum Badge]: https://img.shields.io/discourse/likes?server=https%3A%2F%2Fforum.ratatui.rs&style=flat-square&logo=discourse&label=forum&color=C43AC3
+[Forum]: https://forum.ratatui.rs
+[Sponsors Badge]: https://img.shields.io/github/sponsors/ratatui?logo=github&style=flat-square&color=1370D3

-to actually draw to the terminal.
+<!-- cargo-rdme end -->

-### Widgets
+## Status of this fork

-The library comes with the following list of widgets:
+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 🚀

-  * [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)
+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).

-Click on each item to get an example.
+While we do utilize Discord for coordinating, it's not essential for contributing. We have recently
+launched the [Ratatui Forum][Forum], and our primary open-source workflow is centered around GitHub.
+For bugs and features, we rely on GitHub. Please [Report a bug], [Request a Feature] or [Create a
+Pull Request].

-### Demo
+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.

-The [source code](examples/demo.rs) of the demo gif.
+## 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] folder. Run each example
+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`
+- [templates](https://github.com/ratatui/templates) — Starter templates for
+  bootstrapping a Rust TUI application with Ratatui & crossterm
+- [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 [awesome-ratatui](https://github.com/ratatui/awesome-ratatui) for a curated list of
+awesome apps/libraries built with `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 organization.

 ## License

-[MIT](LICENSE)
-
-## Author
-
-Florian Dehau
+[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/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/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/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/ratatui/issues/147) and
+[#359](https://github.com/ratatui/ratatui/pull/359) for more info on the alpha release process.
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -0,0 +1,9 @@
+# Security Policy
+
+## Supported Versions
+
+We only support the latest version of this crate.
+
+## Reporting a Vulnerability
+
+To report secuirity vulnerability, please use the form at <https://github.com/ratatui/ratatui/security/advisories/new>
--- 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,112 @@
+# 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.test-unit]
+command = [
+    "cargo", "test",
+    "--lib",
+    "--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"
+ctrl-v = "job:coverage-unit-tests-only"
+u = "job:test-unit"
+n = "job:nextest"
--- a/benches/main.rs
+++ b/benches/main.rs
@@ -0,0 +1,22 @@
+pub mod main {
+    pub mod barchart;
+    pub mod block;
+    pub mod buffer;
+    pub mod line;
+    pub mod list;
+    pub mod paragraph;
+    pub mod rect;
+    pub mod sparkline;
+}
+pub use main::*;
+
+criterion::criterion_main!(
+    barchart::benches,
+    block::benches,
+    buffer::benches,
+    line::benches,
+    list::benches,
+    paragraph::benches,
+    rect::benches,
+    sparkline::benches
+);
--- a/benches/main/barchart.rs
+++ b/benches/main/barchart.rs
@@ -0,0 +1,72 @@
+use criterion::{criterion_group, Bencher, BenchmarkId, Criterion};
+use rand::Rng;
+use ratatui::{
+    buffer::Buffer,
+    layout::Rect,
+    prelude::Direction,
+    widgets::{Bar, BarChart, BarGroup, Widget},
+};
+
+/// Benchmark for rendering a barchart.
+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/ratatui/pull/377.
+    bencher.iter_batched(
+        || barchart.clone(),
+        |bench_barchart| {
+            bench_barchart.render(buffer.area, &mut buffer);
+        },
+        criterion::BatchSize::LargeInput,
+    );
+}
+
+criterion_group!(benches, barchart);
--- a/benches/main/block.rs
+++ b/benches/main/block.rs
@@ -0,0 +1,61 @@
+use criterion::{criterion_group, BatchSize, Bencher, Criterion};
+use ratatui::{
+    buffer::Buffer,
+    layout::{Alignment, Rect},
+    widgets::{
+        block::{Position, Title},
+        Block, Padding, Widget,
+    },
+};
+
+/// Benchmark for rendering a block.
+fn block(c: &mut Criterion) {
+    let mut group = c.benchmark_group("block");
+
+    for (width, height) in [
+        (100, 50),  // vertically split screen
+        (200, 50),  // 1080p fullscreen with medium font
+        (256, 256), // Max sized area
+    ] {
+        let buffer_size = Rect::new(0, 0, width, height);
+
+        // Render an empty block
+        group.bench_with_input(
+            format!("render_empty/{width}x{height}"),
+            &Block::new(),
+            |b, block| render(b, block, buffer_size),
+        );
+
+        // Render with all features
+        group.bench_with_input(
+            format!("render_all_feature/{width}x{height}"),
+            &Block::bordered()
+                .padding(Padding::new(5, 5, 2, 2))
+                .title("test title")
+                .title(
+                    Title::from("bottom left title")
+                        .alignment(Alignment::Right)
+                        .position(Position::Bottom),
+                ),
+            |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/ratatui/pull/377.
+    bencher.iter_batched(
+        || block.to_owned(),
+        |bench_block| {
+            bench_block.render(buffer.area, &mut buffer);
+        },
+        BatchSize::SmallInput,
+    );
+}
+
+criterion_group!(benches, block);
--- a/benches/main/buffer.rs
+++ b/benches/main/buffer.rs
@@ -0,0 +1,65 @@
+use criterion::{black_box, BenchmarkId, Criterion};
+use ratatui::{
+    buffer::{Buffer, Cell},
+    layout::Rect,
+    text::Line,
+};
+
+criterion::criterion_group!(benches, empty, filled, with_lines);
+
+const fn rect(size: u16) -> Rect {
+    Rect {
+        x: 0,
+        y: 0,
+        width: size,
+        height: size,
+    }
+}
+
+fn empty(c: &mut Criterion) {
+    let mut group = c.benchmark_group("buffer/empty");
+    for size in [16, 64, 255] {
+        let area = rect(size);
+        group.bench_with_input(BenchmarkId::from_parameter(size), &area, |b, &area| {
+            b.iter(|| {
+                let _buffer = Buffer::empty(black_box(area));
+            });
+        });
+    }
+    group.finish();
+}
+
+/// This likely should have the same performance as `empty`, but it's here for completeness
+/// and to catch any potential performance regressions.
+fn filled(c: &mut Criterion) {
+    let mut group = c.benchmark_group("buffer/filled");
+    for size in [16, 64, 255] {
+        let area = rect(size);
+        let cell = Cell::new("AAAA"); // simulate a multi-byte character
+        group.bench_with_input(
+            BenchmarkId::from_parameter(size),
+            &(area, cell),
+            |b, (area, cell)| {
+                b.iter(|| {
+                    let _buffer = Buffer::filled(black_box(*area), cell.clone());
+                });
+            },
+        );
+    }
+    group.finish();
+}
+
+fn with_lines(c: &mut Criterion) {
+    let mut group = c.benchmark_group("buffer/with_lines");
+    for size in [16, 64, 255] {
+        let word_count = 50;
+        let lines = fakeit::words::sentence(word_count);
+        let lines = lines.lines().map(Line::from);
+        group.bench_with_input(BenchmarkId::from_parameter(size), &lines, |b, lines| {
+            b.iter(|| {
+                let _buffer = Buffer::with_lines(black_box(lines.clone()));
+            });
+        });
+    }
+    group.finish();
+}
--- a/benches/main/line.rs
+++ b/benches/main/line.rs
@@ -0,0 +1,38 @@
+use std::hint::black_box;
+
+use criterion::{criterion_group, Criterion};
+use ratatui::{
+    buffer::Buffer,
+    layout::{Alignment, Rect},
+    style::Stylize,
+    text::Line,
+    widgets::Widget,
+};
+
+fn line_render(criterion: &mut Criterion) {
+    for alignment in [Alignment::Left, Alignment::Center, Alignment::Right] {
+        let mut group = criterion.benchmark_group(format!("line_render/{alignment}"));
+        group.sample_size(1000);
+
+        let line = &Line::from(vec![
+            "This".red(),
+            " ".green(),
+            "is".italic(),
+            " ".blue(),
+            "SPARTA!!".bold(),
+        ])
+        .alignment(alignment);
+
+        for width in [0, 3, 4, 6, 7, 10, 42] {
+            let area = Rect::new(0, 0, width, 1);
+
+            group.bench_function(width.to_string(), |bencher| {
+                let mut buffer = Buffer::empty(area);
+                bencher.iter(|| black_box(line).render(area, &mut buffer));
+            });
+        }
+        group.finish();
+    }
+}
+
+criterion_group!(benches, line_render);
--- a/benches/main/list.rs
+++ b/benches/main/list.rs
@@ -0,0 +1,72 @@
+use criterion::{criterion_group, 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.
+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/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/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);
--- a/benches/main/paragraph.rs
+++ b/benches/main/paragraph.rs
@@ -0,0 +1,94 @@
+use criterion::{black_box, criterion_group, 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.
+fn paragraph(c: &mut Criterion) {
+    let mut group = c.benchmark_group("paragraph");
+    for line_count in [64, 2048, MAX_SCROLL_OFFSET] {
+        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((0, 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((0, 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((0, 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/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 = i64::from(count);
+    let sentence_count = 3;
+    let word_count = 11;
+    fakeit::words::paragraph(count, sentence_count, word_count, "\n".into())
+}
+
+criterion_group!(benches, paragraph);
--- a/benches/main/rect.rs
+++ b/benches/main/rect.rs
@@ -0,0 +1,24 @@
+use criterion::{black_box, criterion_group, BenchmarkId, Criterion};
+use ratatui::layout::Rect;
+
+fn rect_rows_benchmark(c: &mut Criterion) {
+    let rect_sizes = vec![
+        Rect::new(0, 0, 1, 16),
+        Rect::new(0, 0, 1, 1024),
+        Rect::new(0, 0, 1, 65535),
+    ];
+    let mut group = c.benchmark_group("rect_rows");
+    for rect in rect_sizes {
+        group.bench_with_input(BenchmarkId::new("rows", rect.height), &rect, |b, rect| {
+            b.iter(|| {
+                for row in rect.rows() {
+                    // Perform any necessary operations on each row
+                    black_box(row);
+                }
+            });
+        });
+    }
+    group.finish();
+}
+
+criterion_group!(benches, rect_rows_benchmark);
--- a/benches/main/sparkline.rs
+++ b/benches/main/sparkline.rs
@@ -0,0 +1,44 @@
+use criterion::{criterion_group, Bencher, BenchmarkId, Criterion};
+use rand::Rng;
+use ratatui::{
+    buffer::Buffer,
+    layout::Rect,
+    widgets::{Sparkline, Widget},
+};
+
+/// Benchmark for rendering a sparkline.
+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/ratatui/pull/377.
+    bencher.iter_batched(
+        || sparkline.clone(),
+        |bench_sparkline| {
+            bench_sparkline.render(buffer.area, &mut buffer);
+        },
+        criterion::BatchSize::LargeInput,
+    );
+}
+
+criterion_group!(benches, sparkline);
--- a/cliff.toml
+++ b/cliff.toml
@@ -0,0 +1,148 @@
+# git-cliff ~ configuration file
+# https://git-cliff.org/docs/configuration
+
+[remote.github]
+owner = "ratatui"
+repo = "ratatui"
+
+[changelog]
+# changelog header
+header = """
+# Changelog
+
+All notable changes to this project will be documented in this file.
+<!-- ignore lint rules that are often triggered by content generated from commits / git-cliff -->
+<!-- markdownlint-disable line-length no-bare-urls ul-style emphasis-style -->
+"""
+# 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/ratatui/releases/tag/{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }}
+{% endif -%}
+
+{% macro commit(commit) -%}
+- [{{ commit.id | truncate(length=7, end="") }}]({{ "https://github.com/ratatui/ratatui/commit/" ~ commit.id }}) \
+  *({{commit.scope | default(value = "uncategorized") | lower }})* {{ commit.message | upper_first | trim }}\
+  {% if commit.github.username %} by @{{ commit.github.username }}{%- endif -%}\
+  {% if commit.github.pr_number %} in [#{{ commit.github.pr_number }}]({{ self::remote_url() }}/pull/{{ commit.github.pr_number }}){%- endif %}\
+{%- if commit.breaking %} [**breaking**]{% endif %}
+{%- if commit.body %}\n\n{{ commit.body | indent(prefix="  > ", first=true, blank=true) }}
+{%- endif %}
+{%- for footer in commit.footers %}\n
+{%- if footer.token != "Signed-off-by" and footer.token != "Co-authored-by" %}
+  >
+{{ footer.token | indent(prefix="  > ", first=true, blank=true) }}
+{{- footer.separator }}
+{{- footer.value| indent(prefix="  > ", first=false, blank=true)  }}
+{%- endif %}
+{%- endfor %}
+{% 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 %}
+
+{% if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}
+### New Contributors
+{%- endif %}\
+{% for contributor in github.contributors | filter(attribute="is_first_time", value=true) %}
+* @{{ contributor.username }} made their first contribution
+{%- if contributor.pr_number %} in \
+[#{{ contributor.pr_number }}]({{ self::remote_url() }}/pull/{{ contributor.pr_number }}) \
+{%- endif %}
+{%- endfor -%}
+
+{% if version %}
+{% if previous.version %}
+**Full Changelog**: {{ self::remote_url() }}/compare/{{ previous.version }}...{{ version }}
+{% endif %}
+{% else -%}
+  {% raw %}\n{% endraw %}
+{% endif %}
+
+{%- macro remote_url() -%}
+https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}\
+{% endmacro %}
+"""
+
+
+# remove the leading and trailing whitespace from the template
+trim = false
+# changelog footer
+footer = """
+<!-- generated by git-cliff -->
+"""
+postprocessors = [
+  { pattern = '<!-- Please read CONTRIBUTING.md before submitting any pull request. -->', replace = "" },
+  { pattern = '>---+\n', replace = '' },
+  { pattern = ' +\n', replace = "\n" },
+]
+
+[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 = "" },
+  { 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/clippy.toml
+++ b/clippy.toml
@@ -0,0 +1,17 @@
+avoid-breaking-exported-api = false
+
+# https://rust-lang.github.io/rust-clippy/master/index.html#/multiple_crate_versions
+# ratatui -> bitflags v2.3
+# termwiz -> wezterm-blob-leases -> mac_address -> nix -> bitflags v1.3.2
+# crossterm -> all the windows- deps https://github.com/ratatui/ratatui/pull/1064#issuecomment-2078848980
+allowed-duplicate-crates = [
+    "bitflags",
+    "windows-targets",
+    "windows_aarch64_gnullvm",
+    "windows_aarch64_msvc",
+    "windows_i686_gnu",
+    "windows_i686_msvc",
+    "windows_x86_64_gnu",
+    "windows_x86_64_gnullvm",
+    "windows_x86_64_msvc",
+]
--- 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,25 @@
+# configuration for https://github.com/EmbarkStudios/cargo-deny
+
+[licenses]
+version = 2
+confidence-threshold = 0.8
+allow = [
+    "Apache-2.0",
+    "BSD-2-Clause",
+    "BSD-3-Clause",
+    "ISC",
+    "MIT",
+    "Unicode-DFS-2016",
+    "WTFPL",
+]
+
+[advisories]
+version = 2
+
+[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,478 @@
+# Examples
+
+This folder might use unreleased code. View the examples for the latest release instead.
+
+> [!WARNING]
+>
+> There may be backwards incompatible changes in these examples, as they are designed to compile
+> against the `main` branch.
+>
+> There are a few workaround for this problem:
+>
+> - View the examples as they were when the latest version was release by selecting the tag that
+>   matches that version. E.g. <https://github.com/ratatui/ratatui/tree/v0.26.1/examples>.
+> - If you're viewing this file on GitHub, there is a combo box at the top of this page  which
+>   allows you to select any previous tagged version.
+> - To view the code locally, checkout the tag. E.g. `git switch --detach v0.26.1`.
+> - Use the latest [alpha version of Ratatui] in your app. These are released weekly on Saturdays.
+> - Compile your code against the main branch either locally by adding e.g. `path = "../ratatui"` to
+>   the dependency, or remotely by adding `git = "https://github.com/ratatui/ratatui"`
+>
+> For a list of unreleased breaking changes, see [BREAKING-CHANGES.md].
+>
+> We don't keep the CHANGELOG updated with unreleased changes, check the git commit history or run
+> `git-cliff -u` against a cloned version of this repository.
+
+## Design choices
+
+The examples contain some opinionated choices in order to make it easier for newer rustaceans to
+easily be productive in creating applications:
+
+- Each example has an App struct, with methods that implement a main loop, handle events and drawing
+  the UI.
+- We use color_eyre for handling errors and panics. See [How to use color-eyre with Ratatui] on the
+  website for more information about this.
+- Common code is not extracted into a separate file. This makes each example self-contained and easy
+  to read as a whole.
+
+Not every example has been updated with all these points in mind yet, however over time they will
+be. None of the above choices are strictly necessary for Ratatui apps, but these choices make
+examples easier to run, maintain and explain. These choices are designed to help newer users fall
+into the pit of success when incorporating example code into their own apps. We may also eventually
+move some of these design choices into the core of Ratatui to simplify apps.
+
+[How to use color-eyre with Ratatui]: https://ratatui.rs/how-to/develop-apps/color_eyre/
+
+## 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]
+
+## Barchart (Grouped)
+
+Demonstrates the [`BarChart`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.BarChart.html)
+widget with groups. Source: [barchart-grouped.rs](./barchart-grouped.rs).
+
+```shell
+cargo run --example=barchart-grouped --features=crossterm
+```
+
+![Barchart Grouped][barchart-grouped.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
+```
+
+Note: VHs renders full screen animations poorly, so this is a screen capture rather than the output
+of the VHS tape.
+
+<https://github.com/ratatui/ratatui/assets/381361/485e775a-e0b5-4133-899b-1e8aeb56e774>
+
+## Constraint Explorer
+
+Demonstrates the behaviour of each
+[`Constraint`](https://docs.rs/ratatui/latest/ratatui/layout/enum.Constraint.html) option with
+respect to each other across different `Flex` modes.
+
+```shell
+cargo run --example=constraint-explorer --features=crossterm
+```
+
+![Constraint Explorer][constraint-explorer.gif]
+
+## Constraints
+
+Demonstrates how to use
+[`Constraint`](https://docs.rs/ratatui/latest/ratatui/layout/enum.Constraint.html) options for
+defining layout element sizes.
+
+![Constraints][constraints.gif]
+
+```shell
+cargo run --example=constraints --features=crossterm
+```
+
+## 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]
+
+## Flex
+
+Demonstrates the different [`Flex`](https://docs.rs/ratatui/latest/ratatui/layout/enum.Flex.html)
+modes for controlling layout space distribution.
+
+```shell
+cargo run --example=flex --features=crossterm
+```
+
+![Flex][flex.gif]
+
+## Line Gauge
+
+Demonstrates the [`Line
+Gauge`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.LineGauge.html) widget. Source:
+[line_gauge.rs](./line_gauge.rs).
+
+```shell
+cargo run --example=line_gauge --features=crossterm
+```
+
+![LineGauge][line_gauge.gif]
+
+## Hyperlink
+
+Demonstrates how to use OSC 8 to create hyperlinks in the terminal.
+
+```shell
+cargo run --example=hyperlink --features="crossterm unstable-widget-ref"
+```
+
+![Hyperlink][hyperlink.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]
+
+## Minimal
+
+Demonstrates how to create a minimal `Hello World!` program.
+
+```shell
+cargo run --example=minimal --features=crossterm
+```
+
+![Minimal][minimal.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]
+
+## Ratatui-logo
+
+A fun example of using half blocks to render graphics Source:
+[ratatui-logo.rs](./ratatui-logo.rs).
+
+>
+```shell
+cargo run --example=ratatui-logo --features=crossterm
+```
+
+![Ratatui Logo][ratatui-logo.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]
+
+## Tracing
+
+Demonstrates how to use the [tracing crate](https://crates.io/crates/tracing) for logging. Creates
+a file named `tracing.log` in the current directory.
+
+```shell
+cargo run --example=tracing --features=crossterm
+```
+
+![Tracing][tracing.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]
+
+## How to update these 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 `images` git branch to avoid bloating the main
+repository.
+
+<!--
+
+Links to images to make them easier to update in bulk. Use the following script to update and upload
+the examples to the images branch. (Requires push access to the branch).
+
+```shell
+examples/vhs/generate.bash
+```
+-->
+
+[barchart.gif]: https://github.com/ratatui/ratatui/blob/images/examples/barchart.gif?raw=true
+[barchart-grouped.gif]: https://github.com/ratatui/ratatui/blob/images/examples/barchart-grouped.gif?raw=true
+[block.gif]: https://github.com/ratatui/ratatui/blob/images/examples/block.gif?raw=true
+[calendar.gif]: https://github.com/ratatui/ratatui/blob/images/examples/calendar.gif?raw=true
+[canvas.gif]: https://github.com/ratatui/ratatui/blob/images/examples/canvas.gif?raw=true
+[chart.gif]: https://github.com/ratatui/ratatui/blob/images/examples/chart.gif?raw=true
+[colors.gif]: https://github.com/ratatui/ratatui/blob/images/examples/colors.gif?raw=true
+[constraint-explorer.gif]: https://github.com/ratatui/ratatui/blob/images/examples/constraint-explorer.gif?raw=true
+[constraints.gif]: https://github.com/ratatui/ratatui/blob/images/examples/constraints.gif?raw=true
+[custom_widget.gif]: https://github.com/ratatui/ratatui/blob/images/examples/custom_widget.gif?raw=true
+[demo.gif]: https://github.com/ratatui/ratatui/blob/images/examples/demo.gif?raw=true
+[demo2.gif]: https://github.com/ratatui/ratatui/blob/images/examples/demo2.gif?raw=true
+[flex.gif]: https://github.com/ratatui/ratatui/blob/images/examples/flex.gif?raw=true
+[gauge.gif]: https://github.com/ratatui/ratatui/blob/images/examples/gauge.gif?raw=true
+[hello_world.gif]: https://github.com/ratatui/ratatui/blob/images/examples/hello_world.gif?raw=true
+[hyperlink.gif]: https://github.com/ratatui/ratatui/blob/images/examples/hyperlink.gif?raw=true
+[inline.gif]: https://github.com/ratatui/ratatui/blob/images/examples/inline.gif?raw=true
+[layout.gif]: https://github.com/ratatui/ratatui/blob/images/examples/layout.gif?raw=true
+[list.gif]: https://github.com/ratatui/ratatui/blob/images/examples/list.gif?raw=true
+[line_gauge.gif]: https://github.com/ratatui/ratatui/blob/images/examples/line_gauge.gif?raw=true
+[minimal.gif]: https://github.com/ratatui/ratatui/blob/images/examples/minimal.gif?raw=true
+[modifiers.gif]: https://github.com/ratatui/ratatui/blob/images/examples/modifiers.gif?raw=true
+[panic.gif]: https://github.com/ratatui/ratatui/blob/images/examples/panic.gif?raw=true
+[paragraph.gif]: https://github.com/ratatui/ratatui/blob/images/examples/paragraph.gif?raw=true
+[popup.gif]: https://github.com/ratatui/ratatui/blob/images/examples/popup.gif?raw=true
+[ratatui-logo.gif]: https://github.com/ratatui/ratatui/blob/images/examples/ratatui-logo.gif?raw=true
+[scrollbar.gif]: https://github.com/ratatui/ratatui/blob/images/examples/scrollbar.gif?raw=true
+[sparkline.gif]: https://github.com/ratatui/ratatui/blob/images/examples/sparkline.gif?raw=true
+[table.gif]:  https://vhs.charm.sh/vhs-6njXBytDf0rwPufUtmSSpI.gif
+[tabs.gif]: https://github.com/ratatui/ratatui/blob/images/examples/tabs.gif?raw=true
+[tracing.gif]: https://github.com/ratatui/ratatui/blob/images/examples/tracing.gif?raw=true
+[user_input.gif]: https://github.com/ratatui/ratatui/blob/images/examples/user_input.gif?raw=true
+
+[alpha version of Ratatui]: https://crates.io/crates/ratatui/versions
+[BREAKING-CHANGES.md]: https://github.com/ratatui/ratatui/blob/main/BREAKING-CHANGES.md
--- a/examples/async.rs
+++ b/examples/async.rs
@@ -0,0 +1,258 @@
+//! # [Ratatui] Async example
+//!
+//! This example demonstrates how to use Ratatui with widgets that fetch data asynchronously. It
+//! uses the `octocrab` crate to fetch a list of pull requests from the GitHub API. You will need an
+//! environment variable named `GITHUB_TOKEN` with a valid GitHub personal access token. The token
+//! does not need any special permissions.
+//!
+//! <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token>
+//! <https://github.com/settings/tokens/new> to create a new token (select classic, and no scopes)
+//!
+//! This example does not cover message passing between threads, it only demonstrates how to manage
+//! shared state between the main thread and a background task, which acts mostly as a one-shot
+//! fetcher. For more complex scenarios, you may need to use channels or other synchronization
+//! primitives.
+//!
+//! A simple app might have multiple widgets that fetch data from different sources, and each widget
+//! would have its own background task to fetch the data. The main thread would then render the
+//! widgets with the latest data.
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+use std::{
+    sync::{Arc, RwLock},
+    time::Duration,
+};
+
+use color_eyre::{eyre::Context, Result, Section};
+use futures::StreamExt;
+use octocrab::{
+    params::{pulls::Sort, Direction},
+    OctocrabBuilder, Page,
+};
+use ratatui::{
+    buffer::Buffer,
+    crossterm::event::{Event, EventStream, KeyCode, KeyEventKind},
+    layout::{Constraint, Layout, Rect},
+    style::{Style, Stylize},
+    text::Line,
+    widgets::{Block, HighlightSpacing, Row, StatefulWidget, Table, TableState, Widget},
+    DefaultTerminal, Frame,
+};
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    color_eyre::install()?;
+    init_octocrab()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal).await;
+    ratatui::restore();
+    app_result
+}
+
+fn init_octocrab() -> Result<()> {
+    let token = std::env::var("GITHUB_TOKEN")
+        .wrap_err("The GITHUB_TOKEN environment variable was not found")
+        .suggestion(
+            "Go to https://github.com/settings/tokens/new to create a token, and re-run:
+            GITHUB_TOKEN=ghp_... cargo run --example async --features crossterm",
+        )?;
+    let crab = OctocrabBuilder::new().personal_token(token).build()?;
+    octocrab::initialise(crab);
+    Ok(())
+}
+
+#[derive(Debug, Default)]
+struct App {
+    should_quit: bool,
+    pull_requests: PullRequestListWidget,
+}
+
+impl App {
+    const FRAMES_PER_SECOND: f32 = 60.0;
+
+    pub async fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        self.pull_requests.run();
+
+        let period = Duration::from_secs_f32(1.0 / Self::FRAMES_PER_SECOND);
+        let mut interval = tokio::time::interval(period);
+        let mut events = EventStream::new();
+
+        while !self.should_quit {
+            tokio::select! {
+                _ = interval.tick() => { terminal.draw(|frame| self.draw(frame))?; },
+                Some(Ok(event)) = events.next() => self.handle_event(&event),
+            }
+        }
+        Ok(())
+    }
+
+    fn draw(&self, frame: &mut Frame) {
+        let vertical = Layout::vertical([Constraint::Length(1), Constraint::Fill(1)]);
+        let [title_area, body_area] = vertical.areas(frame.area());
+        let title = Line::from("Ratatui async example").centered().bold();
+        frame.render_widget(title, title_area);
+        frame.render_widget(&self.pull_requests, body_area);
+    }
+
+    fn handle_event(&mut self, event: &Event) {
+        if let Event::Key(key) = event {
+            if key.kind == KeyEventKind::Press {
+                match key.code {
+                    KeyCode::Char('q') | KeyCode::Esc => self.should_quit = true,
+                    KeyCode::Char('j') | KeyCode::Down => self.pull_requests.scroll_down(),
+                    KeyCode::Char('k') | KeyCode::Up => self.pull_requests.scroll_up(),
+                    _ => {}
+                }
+            }
+        }
+    }
+}
+
+/// A widget that displays a list of pull requests.
+///
+/// This is an async widget that fetches the list of pull requests from the GitHub API. It contains
+/// an inner `Arc<RwLock<PullRequestListState>>` that holds the state of the widget. Cloning the
+/// widget will clone the Arc, so you can pass it around to other threads, and this is used to spawn
+/// a background task to fetch the pull requests.
+#[derive(Debug, Clone, Default)]
+struct PullRequestListWidget {
+    state: Arc<RwLock<PullRequestListState>>,
+}
+
+#[derive(Debug, Default)]
+struct PullRequestListState {
+    pull_requests: Vec<PullRequest>,
+    loading_state: LoadingState,
+    table_state: TableState,
+}
+
+#[derive(Debug, Clone)]
+struct PullRequest {
+    id: String,
+    title: String,
+    url: String,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+enum LoadingState {
+    #[default]
+    Idle,
+    Loading,
+    Loaded,
+    Error(String),
+}
+
+impl PullRequestListWidget {
+    /// Start fetching the pull requests in the background.
+    ///
+    /// This method spawns a background task that fetches the pull requests from the GitHub API.
+    /// The result of the fetch is then passed to the `on_load` or `on_err` methods.
+    fn run(&self) {
+        let this = self.clone(); // clone the widget to pass to the background task
+        tokio::spawn(this.fetch_pulls());
+    }
+
+    async fn fetch_pulls(self) {
+        // this runs once, but you could also run this in a loop, using a channel that accepts
+        // messages to refresh on demand, or with an interval timer to refresh every N seconds
+        self.set_loading_state(LoadingState::Loading);
+        match octocrab::instance()
+            .pulls("ratatui", "ratatui")
+            .list()
+            .sort(Sort::Updated)
+            .direction(Direction::Descending)
+            .send()
+            .await
+        {
+            Ok(page) => self.on_load(&page),
+            Err(err) => self.on_err(&err),
+        }
+    }
+    fn on_load(&self, page: &Page<OctoPullRequest>) {
+        let prs = page.items.iter().map(Into::into);
+        let mut state = self.state.write().unwrap();
+        state.loading_state = LoadingState::Loaded;
+        state.pull_requests.extend(prs);
+        if !state.pull_requests.is_empty() {
+            state.table_state.select(Some(0));
+        }
+    }
+
+    fn on_err(&self, err: &octocrab::Error) {
+        self.set_loading_state(LoadingState::Error(err.to_string()));
+    }
+
+    fn set_loading_state(&self, state: LoadingState) {
+        self.state.write().unwrap().loading_state = state;
+    }
+
+    fn scroll_down(&self) {
+        self.state.write().unwrap().table_state.scroll_down_by(1);
+    }
+
+    fn scroll_up(&self) {
+        self.state.write().unwrap().table_state.scroll_up_by(1);
+    }
+}
+
+type OctoPullRequest = octocrab::models::pulls::PullRequest;
+
+impl From<&OctoPullRequest> for PullRequest {
+    fn from(pr: &OctoPullRequest) -> Self {
+        Self {
+            id: pr.number.to_string(),
+            title: pr.title.as_ref().unwrap().to_string(),
+            url: pr
+                .html_url
+                .as_ref()
+                .map(ToString::to_string)
+                .unwrap_or_default(),
+        }
+    }
+}
+
+impl Widget for &PullRequestListWidget {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let mut state = self.state.write().unwrap();
+
+        // a block with a right aligned title with the loading state on the right
+        let loading_state = Line::from(format!("{:?}", state.loading_state)).right_aligned();
+        let block = Block::bordered()
+            .title("Pull Requests")
+            .title(loading_state)
+            .title_bottom("j/k to scroll, q to quit");
+
+        // a table with the list of pull requests
+        let rows = state.pull_requests.iter();
+        let widths = [
+            Constraint::Length(5),
+            Constraint::Fill(1),
+            Constraint::Max(49),
+        ];
+        let table = Table::new(rows, widths)
+            .block(block)
+            .highlight_spacing(HighlightSpacing::Always)
+            .highlight_symbol(">>")
+            .highlight_style(Style::new().on_blue());
+
+        StatefulWidget::render(table, area, buf, &mut state.table_state);
+    }
+}
+
+impl From<&PullRequest> for Row<'_> {
+    fn from(pr: &PullRequest) -> Self {
+        let pr = pr.clone();
+        Row::new(vec![pr.id, pr.title, pr.url])
+    }
+}
--- a/examples/barchart-grouped.rs
+++ b/examples/barchart-grouped.rs
@@ -0,0 +1,211 @@
+//! # [Ratatui] `BarChart` example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+use std::iter::zip;
+
+use color_eyre::Result;
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Constraint, Direction, Layout},
+    style::{Color, Style, Stylize},
+    text::Line,
+    widgets::{Bar, BarChart, BarGroup, Block},
+    DefaultTerminal, Frame,
+};
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
+const COMPANY_COUNT: usize = 3;
+const PERIOD_COUNT: usize = 4;
+
+struct App {
+    should_exit: bool,
+    companies: [Company; COMPANY_COUNT],
+    revenues: [Revenues; PERIOD_COUNT],
+}
+
+struct Revenues {
+    period: &'static str,
+    revenues: [u32; COMPANY_COUNT],
+}
+
+struct Company {
+    short_name: &'static str,
+    name: &'static str,
+    color: Color,
+}
+
+impl App {
+    const fn new() -> Self {
+        Self {
+            should_exit: false,
+            companies: fake_companies(),
+            revenues: fake_revenues(),
+        }
+    }
+
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        while !self.should_exit {
+            terminal.draw(|frame| self.draw(frame))?;
+            self.handle_events()?;
+        }
+        Ok(())
+    }
+
+    fn handle_events(&mut self) -> Result<()> {
+        if let Event::Key(key) = event::read()? {
+            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                self.should_exit = true;
+            }
+        }
+        Ok(())
+    }
+
+    fn draw(&self, frame: &mut Frame) {
+        use Constraint::{Fill, Length, Min};
+        let vertical = Layout::vertical([Length(1), Fill(1), Min(20)]).spacing(1);
+        let [title, top, bottom] = vertical.areas(frame.area());
+
+        frame.render_widget("Grouped Barchart".bold().into_centered_line(), title);
+        frame.render_widget(self.vertical_revenue_barchart(), top);
+        frame.render_widget(self.horizontal_revenue_barchart(), bottom);
+    }
+
+    /// Create a vertical revenue bar chart with the data from the `revenues` field.
+    fn vertical_revenue_barchart(&self) -> BarChart<'_> {
+        let mut barchart = BarChart::default()
+            .block(Block::new().title(Line::from("Company revenues (Vertical)").centered()))
+            .bar_gap(0)
+            .bar_width(6)
+            .group_gap(2);
+
+        for group in self
+            .revenues
+            .iter()
+            .map(|revenue| revenue.to_vertical_bar_group(&self.companies))
+        {
+            barchart = barchart.data(group);
+        }
+        barchart
+    }
+
+    /// Create a horizontal revenue bar chart with the data from the `revenues` field.
+    fn horizontal_revenue_barchart(&self) -> BarChart<'_> {
+        let title = Line::from("Company Revenues (Horizontal)").centered();
+        let mut barchart = BarChart::default()
+            .block(Block::new().title(title))
+            .bar_width(1)
+            .group_gap(2)
+            .bar_gap(0)
+            .direction(Direction::Horizontal);
+        for group in self
+            .revenues
+            .iter()
+            .map(|revenue| revenue.to_horizontal_bar_group(&self.companies))
+        {
+            barchart = barchart.data(group);
+        }
+        barchart
+    }
+}
+
+/// Generate fake company data
+const fn fake_companies() -> [Company; COMPANY_COUNT] {
+    [
+        Company::new("BAKE", "Bake my day", Color::LightRed),
+        Company::new("BITE", "Bits and Bites", Color::Blue),
+        Company::new("TART", "Tart of the Table", Color::White),
+    ]
+}
+
+/// Some fake revenue data
+const fn fake_revenues() -> [Revenues; PERIOD_COUNT] {
+    [
+        Revenues::new("Jan", [8500, 6500, 7000]),
+        Revenues::new("Feb", [9000, 7500, 8500]),
+        Revenues::new("Mar", [9500, 4500, 8200]),
+        Revenues::new("Apr", [6300, 4000, 5000]),
+    ]
+}
+
+impl Revenues {
+    /// Create a new instance of `Revenues`
+    const fn new(period: &'static str, revenues: [u32; COMPANY_COUNT]) -> Self {
+        Self { period, revenues }
+    }
+
+    /// Create a `BarGroup` with vertical bars for each company
+    fn to_vertical_bar_group<'a>(&self, companies: &'a [Company]) -> BarGroup<'a> {
+        let bars: Vec<Bar> = zip(companies, self.revenues)
+            .map(|(company, revenue)| company.vertical_revenue_bar(revenue))
+            .collect();
+        BarGroup::default()
+            .label(Line::from(self.period).centered())
+            .bars(&bars)
+    }
+
+    /// Create a `BarGroup` with horizontal bars for each company
+    fn to_horizontal_bar_group<'a>(&'a self, companies: &'a [Company]) -> BarGroup<'a> {
+        let bars: Vec<Bar> = zip(companies, self.revenues)
+            .map(|(company, revenue)| company.horizontal_revenue_bar(revenue))
+            .collect();
+        BarGroup::default()
+            .label(Line::from(self.period).centered())
+            .bars(&bars)
+    }
+}
+
+impl Company {
+    /// Create a new instance of `Company`
+    const fn new(short_name: &'static str, name: &'static str, color: Color) -> Self {
+        Self {
+            short_name,
+            name,
+            color,
+        }
+    }
+
+    /// Create a vertical revenue bar for the company
+    ///
+    /// The label is the short name of the company, and will be displayed under the bar
+    fn vertical_revenue_bar(&self, revenue: u32) -> Bar {
+        let text_value = format!("{:.1}M", f64::from(revenue) / 1000.);
+        Bar::default()
+            .label(self.short_name.into())
+            .value(u64::from(revenue))
+            .text_value(text_value)
+            .style(self.color)
+            .value_style(Style::new().fg(Color::Black).bg(self.color))
+    }
+
+    /// Create a horizontal revenue bar for the company
+    ///
+    /// The label is the long name of the company combined with the revenue and will be displayed
+    /// on the bar
+    fn horizontal_revenue_bar(&self, revenue: u32) -> Bar {
+        let text_value = format!("{} ({:.1} M)", self.name, f64::from(revenue) / 1000.);
+        Bar::default()
+            .value(u64::from(revenue))
+            .text_value(text_value)
+            .style(self.color)
+            .value_style(Style::new().fg(Color::Black).bg(self.color))
+    }
+}
--- a/examples/barchart.rs
+++ b/examples/barchart.rs
@@ -1,160 +1,136 @@
-extern crate tui;
-extern crate termion;
+//! # [Ratatui] `BarChart` example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md

-use std::io;
-use std::thread;
-use std::time;
-use std::sync::mpsc;
+use color_eyre::Result;
+use rand::{thread_rng, Rng};
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Constraint, Direction, Layout},
+    style::{Color, Style, Stylize},
+    text::Line,
+    widgets::{Bar, BarChart, BarGroup, Block},
+    DefaultTerminal, Frame,
+};

-use termion::event;
-use termion::input::TermRead;
-
-use tui::Terminal;
-use tui::backend::TermionBackend;
-use tui::widgets::{Widget, Block, border, BarChart};
-use tui::layout::{Group, Direction, Size};
-use tui::style::{Style, Color, Modifier};
-
-struct App<'a> {
-    data: Vec<(&'a str, u64)>,
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
 }

-impl<'a> App<'a> {
-    fn new() -> App<'a> {
-        App {
-            data: 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)],
+struct App {
+    should_exit: bool,
+    temperatures: Vec<u8>,
+}
+
+impl App {
+    fn new() -> Self {
+        let mut rng = thread_rng();
+        let temperatures = (0..24).map(|_| rng.gen_range(50..90)).collect();
+        Self {
+            should_exit: false,
+            temperatures,
        }
    }

-    fn advance(&mut self) {
-        let value = self.data.pop().unwrap();
-        self.data.insert(0, value);
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        while !self.should_exit {
+            terminal.draw(|frame| self.draw(frame))?;
+            self.handle_events()?;
+        }
+        Ok(())
+    }
+
+    fn handle_events(&mut self) -> Result<()> {
+        if let Event::Key(key) = event::read()? {
+            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                self.should_exit = true;
+            }
+        }
+        Ok(())
+    }
+
+    fn draw(&self, frame: &mut Frame) {
+        let [title, vertical, horizontal] = Layout::vertical([
+            Constraint::Length(1),
+            Constraint::Fill(1),
+            Constraint::Fill(1),
+        ])
+        .spacing(1)
+        .areas(frame.area());
+
+        frame.render_widget("Barchart".bold().into_centered_line(), title);
+        frame.render_widget(vertical_barchart(&self.temperatures), vertical);
+        frame.render_widget(horizontal_barchart(&self.temperatures), horizontal);
    }
 }

-enum Event {
-    Input(event::Key),
-    Tick,
+/// Create a vertical bar chart from the temperatures data.
+fn vertical_barchart(temperatures: &[u8]) -> BarChart {
+    let bars: Vec<Bar> = temperatures
+        .iter()
+        .enumerate()
+        .map(|(hour, value)| vertical_bar(hour, value))
+        .collect();
+    let title = Line::from("Weather (Vertical)").centered();
+    BarChart::default()
+        .data(BarGroup::default().bars(&bars))
+        .block(Block::new().title(title))
+        .bar_width(5)
 }

-fn main() {
-    // Terminal initialization
-    let backend = TermionBackend::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();
-    draw(&mut terminal, &app);
-
-    loop {
-        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);
-    }
-
-    terminal.show_cursor().unwrap();
+fn vertical_bar(hour: usize, temperature: &u8) -> Bar {
+    Bar::default()
+        .value(u64::from(*temperature))
+        .label(Line::from(format!("{hour:>02}:00")))
+        .text_value(format!("{temperature:>3}°"))
+        .style(temperature_style(*temperature))
+        .value_style(temperature_style(*temperature).reversed())
 }

-fn draw(t: &mut Terminal<TermionBackend>, app: &App) {
-
-    let size = t.size().unwrap();
-
-    Group::default()
-        .direction(Direction::Vertical)
-        .margin(2)
-        .sizes(&[Size::Percent(50), Size::Percent(50)])
-        .render(t, &size, |t, chunks| {
-            BarChart::default()
-                .block(Block::default().title("Data1").borders(border::ALL))
-                .data(&app.data)
-                .bar_width(9)
-                .style(Style::default().fg(Color::Yellow))
-                .value_style(Style::default().fg(Color::Black).bg(Color::Yellow))
-                .render(t, &chunks[0]);
-            Group::default()
-                .direction(Direction::Horizontal)
-                .sizes(&[Size::Percent(50), Size::Percent(50)])
-                .render(t, &chunks[1], |t, chunks| {
-                    BarChart::default()
-                        .block(Block::default().title("Data2").borders(border::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(t, &chunks[0]);
-                    BarChart::default()
-                        .block(Block::default().title("Data3").borders(border::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(t, &chunks[1]);
-                })
-        });
-
-    t.draw().unwrap();
+/// Create a horizontal bar chart from the temperatures data.
+fn horizontal_barchart(temperatures: &[u8]) -> BarChart {
+    let bars: Vec<Bar> = temperatures
+        .iter()
+        .enumerate()
+        .map(|(hour, value)| horizontal_bar(hour, value))
+        .collect();
+    let title = Line::from("Weather (Horizontal)").centered();
+    BarChart::default()
+        .block(Block::new().title(title))
+        .data(BarGroup::default().bars(&bars))
+        .bar_width(1)
+        .bar_gap(0)
+        .direction(Direction::Horizontal)
+}
+
+fn horizontal_bar(hour: usize, temperature: &u8) -> Bar {
+    let style = temperature_style(*temperature);
+    Bar::default()
+        .value(u64::from(*temperature))
+        .label(Line::from(format!("{hour:>02}:00")))
+        .text_value(format!("{temperature:>3}°"))
+        .style(style)
+        .value_style(style.reversed())
+}
+
+/// create a yellow to red value based on the value (50-90)
+fn temperature_style(value: u8) -> Style {
+    let green = (255.0 * (1.0 - f64::from(value - 50) / 40.0)) as u8;
+    let color = Color::Rgb(255, green, 0);
+    Style::new().fg(color)
 }
--- a/examples/block.rs
+++ b/examples/block.rs
@@ -1,79 +1,214 @@
-extern crate tui;
-extern crate termion;
+//! # [Ratatui] Block example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md

-use std::io;
-use termion::event;
-use termion::input::TermRead;
+use color_eyre::Result;
+use itertools::Itertools;
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Alignment, Constraint, Layout, Rect},
+    style::{Style, Stylize},
+    text::Line,
+    widgets::{
+        block::{Position, Title},
+        Block, BorderType, Borders, Padding, Paragraph, Wrap,
+    },
+    DefaultTerminal, Frame,
+};

-use tui::Terminal;
-use tui::backend::TermionBackend;
-use tui::widgets::{Widget, Block, border};
-use tui::layout::{Group, Direction, Size};
-use tui::style::{Style, Color, Modifier};
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let result = run(terminal);
+    ratatui::restore();
+    result
+}

-fn main() {
-    let mut terminal = Terminal::new(TermionBackend::new().unwrap()).unwrap();
-    let stdin = io::stdin();
-    terminal.clear().unwrap();
-    terminal.hide_cursor().unwrap();
-    draw(&mut terminal);
-    for c in stdin.keys() {
-        draw(&mut terminal);
-        let evt = c.unwrap();
-        if evt == event::Key::Char('q') {
-            break;
+fn run(mut terminal: DefaultTerminal) -> Result<()> {
+    loop {
+        terminal.draw(draw)?;
+        if let Event::Key(key) = event::read()? {
+            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                break Ok(());
+            }
        }
    }
-    terminal.show_cursor().unwrap();
 }

-fn draw(t: &mut Terminal<TermionBackend>) {
+fn draw(frame: &mut Frame) {
+    let (title_area, layout) = calculate_layout(frame.area());

-    let size = t.size().unwrap();
+    render_title(frame, title_area);

-    // 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(border::ALL)
-        .render(t, &size);
-    Group::default()
-        .direction(Direction::Vertical)
-        .margin(4)
-        .sizes(&[Size::Percent(50), Size::Percent(50)])
-        .render(t, &size, |t, chunks| {
-            Group::default()
-                .direction(Direction::Horizontal)
-                .sizes(&[Size::Percent(50), Size::Percent(50)])
-                .render(t, &chunks[0], |t, chunks| {
-                    Block::default()
-                        .title("With background")
-                        .title_style(Style::default().fg(Color::Yellow))
-                        .style(Style::default().bg(Color::Green))
-                        .render(t, &chunks[0]);
-                    Block::default()
-                        .title("Styled title")
-                        .title_style(Style::default()
-                            .fg(Color::White)
-                            .bg(Color::Red)
-                            .modifier(Modifier::Bold))
-                        .render(t, &chunks[1]);
-                });
-            Group::default()
-                .direction(Direction::Horizontal)
-                .sizes(&[Size::Percent(50), Size::Percent(50)])
-                .render(t, &chunks[1], |t, chunks| {
-                    Block::default()
-                        .title("With borders")
-                        .borders(border::ALL)
-                        .render(t, &chunks[0]);
-                    Block::default()
-                        .title("With styled borders")
-                        .border_style(Style::default().fg(Color::Cyan))
-                        .borders(border::LEFT | border::RIGHT)
-                        .render(t, &chunks[1]);
-                });
-        });
+    let paragraph = placeholder_paragraph();

-    t.draw().unwrap();
+    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 main_layout = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
+    let block_layout = Layout::vertical([Constraint::Max(4); 9]);
+    let [title_area, main_area] = main_layout.areas(area);
+    let main_areas = block_layout
+        .split(main_area)
+        .iter()
+        .map(|&area| {
+            Layout::horizontal([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:#?}"));
+    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::bordered()
+        .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::bordered()
+        .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::bordered()
+        .style(Style::new().blue().on_white().bold().italic())
+        .title("Styled block");
+    frame.render_widget(paragraph.clone().block(block), area);
+}
+
+fn render_styled_title(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
+    let block = Block::bordered()
+        .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::bordered().title(title);
+    frame.render_widget(paragraph.clone().block(block), area);
+}
+
+fn render_multiple_titles(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
+    let block = Block::bordered()
+        .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::bordered()
+        .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::bordered()
+        .padding(Padding::new(5, 10, 1, 2))
+        .title("Padding");
+    frame.render_widget(paragraph.clone().block(block), area);
+}
+
+fn render_nested_blocks(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
+    let outer_block = Block::bordered().title("Outer block");
+    let inner_block = Block::bordered().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/calendar.rs
+++ b/examples/calendar.rs
@@ -0,0 +1,249 @@
+//! # [Ratatui] Calendar example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+use color_eyre::Result;
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Constraint, Layout, Margin},
+    style::{Color, Modifier, Style},
+    widgets::calendar::{CalendarEventStore, DateStyler, Monthly},
+    DefaultTerminal, Frame,
+};
+use time::{Date, Month, OffsetDateTime};
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let result = run(terminal);
+    ratatui::restore();
+    result
+}
+
+fn run(mut terminal: DefaultTerminal) -> Result<()> {
+    loop {
+        terminal.draw(draw)?;
+        if let Event::Key(key) = event::read()? {
+            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                break Ok(());
+            }
+        }
+    }
+}
+
+fn draw(frame: &mut Frame) {
+    let area = frame.area().inner(Margin {
+        vertical: 1,
+        horizontal: 1,
+    });
+
+    let mut start = OffsetDateTime::now_local()
+        .unwrap()
+        .date()
+        .replace_month(Month::January)
+        .unwrap()
+        .replace_day(1)
+        .unwrap();
+
+    let list = make_dates(start.year());
+
+    let rows = Layout::vertical([Constraint::Ratio(1, 3); 3]).split(area);
+    let cols = rows.iter().flat_map(|row| {
+        Layout::horizontal([Constraint::Ratio(1, 4); 4])
+            .split(*row)
+            .to_vec()
+    });
+    for col in cols {
+        let cal = cals::get_cal(start.month(), start.year(), &list);
+        frame.render_widget(cal, col);
+        start = start.replace_month(start.month().next()).unwrap();
+    }
+}
+
+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 {
+    #[allow(clippy::wildcard_imports)]
+    use super::*;
+
+    pub fn get_cal<'a, DS: DateStyler>(m: Month, y: i32, es: DS) -> Monthly<'a, DS> {
+        match m {
+            Month::May => example1(m, y, es),
+            Month::June => example2(m, y, es),
+            Month::July | Month::December => example3(m, y, es),
+            Month::February => example4(m, y, es),
+            Month::November => example5(m, y, es),
+            _ => default(m, y, es),
+        }
+    }
+
+    fn default<'a, DS: DateStyler>(m: Month, y: i32, es: DS) -> Monthly<'a, DS> {
+        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, DS: DateStyler>(m: Month, y: i32, es: DS) -> Monthly<'a, DS> {
+        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, DS: DateStyler>(m: Month, y: i32, es: DS) -> Monthly<'a, DS> {
+        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, DS: DateStyler>(m: Month, y: i32, es: DS) -> Monthly<'a, DS> {
+        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, DS: DateStyler>(m: Month, y: i32, es: DS) -> Monthly<'a, DS> {
+        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, DS: DateStyler>(m: Month, y: i32, es: DS) -> Monthly<'a, DS> {
+        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/canvas.rs
+++ b/examples/canvas.rs
@@ -1,201 +1,200 @@
-extern crate tui;
-extern crate termion;
+//! # [Ratatui] Canvas example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md

-use std::io;
-use std::thread;
-use std::time;
-use std::sync::mpsc;
+use std::time::{Duration, Instant};

-use termion::event;
-use termion::input::TermRead;
+use color_eyre::Result;
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode},
+    layout::{Constraint, Layout, Rect},
+    style::{Color, Stylize},
+    symbols::Marker,
+    widgets::{
+        canvas::{Canvas, Circle, Map, MapResolution, Rectangle},
+        Block, Widget,
+    },
+    DefaultTerminal, Frame,
+};

-use tui::Terminal;
-use tui::backend::TermionBackend;
-use tui::widgets::{Widget, Block, border};
-use tui::widgets::canvas::{Canvas, Map, MapResolution, Line};
-use tui::layout::{Group, Rect, Direction, Size};
-use tui::style::Color;
-
-struct App {
-    size: Rect,
-    x: f64,
-    y: f64,
-    ball: Rect,
-    playground: Rect,
-    vx: u16,
-    vy: u16,
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
 }

+struct App {
+    x: f64,
+    y: f64,
+    ball: Circle,
+    playground: Rect,
+    vx: f64,
+    vy: f64,
+    tick_count: u64,
+    marker: Marker,
+}

 impl App {
-    fn new() -> App {
-        App {
-            size: Default::default(),
+    fn new() -> Self {
+        Self {
            x: 0.0,
            y: 0.0,
-            ball: Rect::new(20, 20, 10, 10),
-            playground: Rect::new(10, 10, 100, 100),
-            vx: 1,
-            vy: 1,
+            ball: Circle {
+                x: 20.0,
+                y: 40.0,
+                radius: 10.0,
+                color: Color::Yellow,
+            },
+            playground: Rect::new(10, 10, 200, 100),
+            vx: 1.0,
+            vy: 1.0,
+            tick_count: 0,
+            marker: Marker::Dot,
        }
    }

-    fn advance(&mut self) {
-        if self.ball.left() < self.playground.left() ||
-           self.ball.right() > self.playground.right() {
-            self.vx = !self.vx;
-        } else if self.ball.top() < self.playground.top() ||
-                  self.ball.bottom() > self.playground.bottom() {
-            self.vy = !self.vy;
+    pub fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        let tick_rate = Duration::from_millis(16);
+        let mut last_tick = Instant::now();
+        loop {
+            terminal.draw(|frame| self.draw(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 Ok(()),
+                        KeyCode::Down | KeyCode::Char('j') => self.y += 1.0,
+                        KeyCode::Up | KeyCode::Char('k') => self.y -= 1.0,
+                        KeyCode::Right | KeyCode::Char('l') => self.x += 1.0,
+                        KeyCode::Left | KeyCode::Char('h') => self.x -= 1.0,
+                        _ => {}
+                    }
+                }
+            }
+
+            if last_tick.elapsed() >= tick_rate {
+                self.on_tick();
+                last_tick = Instant::now();
+            }
        }
+    }
+
+    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 < f64::from(playground.left())
+            || ball.x + ball.radius > f64::from(playground.right())
+        {
+            self.vx = -self.vx;
+        }
+        if ball.y - ball.radius < f64::from(playground.top())
+            || ball.y + ball.radius > f64::from(playground.bottom())
+        {
+            self.vy = -self.vy;
+        }
+
        self.ball.x += self.vx;
        self.ball.y += self.vy;
    }
-}

-enum Event {
-    Input(event::Key),
-    Tick,
-}
+    fn draw(&self, frame: &mut Frame) {
+        let horizontal =
+            Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)]);
+        let vertical = Layout::vertical([Constraint::Percentage(50), Constraint::Percentage(50)]);
+        let [map, right] = horizontal.areas(frame.area());
+        let [pong, boxes] = vertical.areas(right);

-fn main() {
-    // Terminal initialization
-    let backend = TermionBackend::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();
-    let size = terminal.size().unwrap();
-    app.size = size;
-    draw(&mut terminal, &app);
-
-    loop {
-        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;
-                    }
-
-                    _ => {}
-                }
-            }
-            Event::Tick => {
-                app.advance();
-            }
-        }
-        let size = terminal.size().unwrap();
-        if size != app.size {
-            app.size = size;
-            terminal.resize(size).unwrap();
-        }
-        draw(&mut terminal, &app);
+        frame.render_widget(self.map_canvas(), map);
+        frame.render_widget(self.pong_canvas(), pong);
+        frame.render_widget(self.boxes_canvas(boxes), boxes);
    }

-    terminal.show_cursor().unwrap();
-}
-
-fn draw(t: &mut Terminal<TermionBackend>, app: &App) {
-
-
-    Group::default()
-        .direction(Direction::Horizontal)
-        .sizes(&[Size::Percent(50), Size::Percent(50)])
-        .render(t, &app.size, |t, chunks| {
-            Canvas::default()
-                .block(Block::default()
-                    .borders(border::ALL)
-                    .title("World"))
-                .paint(|ctx| {
-                    ctx.draw(&Map {
-                        color: Color::White,
-                        resolution: MapResolution::High,
-                    });
-                    ctx.print(app.x, -app.y, "You are here", Color::Yellow);
-                })
-                .x_bounds([-180.0, 180.0])
-                .y_bounds([-90.0, 90.0])
-                .render(t, &chunks[0]);
-            Canvas::default()
-                .block(Block::default()
-                    .borders(border::ALL)
-                    .title("List"))
-                .paint(|ctx| {
-                    ctx.draw(&Line {
-                        x1: app.ball.left() as f64,
-                        y1: app.ball.top() as f64,
-                        x2: app.ball.right() as f64,
-                        y2: app.ball.top() as f64,
-                        color: Color::Yellow,
-                    });
-                    ctx.draw(&Line {
-                        x1: app.ball.right() as f64,
-                        y1: app.ball.top() as f64,
-                        x2: app.ball.right() as f64,
-                        y2: app.ball.bottom() as f64,
-                        color: Color::Yellow,
-                    });
-                    ctx.draw(&Line {
-                        x1: app.ball.right() as f64,
-                        y1: app.ball.bottom() as f64,
-                        x2: app.ball.left() as f64,
-                        y2: app.ball.bottom() as f64,
-                        color: Color::Yellow,
-                    });
-                    ctx.draw(&Line {
-                        x1: app.ball.left() as f64,
-                        y1: app.ball.bottom() as f64,
-                        x2: app.ball.left() as f64,
-                        y2: app.ball.top() as f64,
-                        color: Color::Yellow,
-                    });
-                })
-                .x_bounds([10.0, 110.0])
-                .y_bounds([10.0, 110.0])
-                .render(t, &chunks[1]);
-        });
-
-    t.draw().unwrap();
+    fn map_canvas(&self) -> impl Widget + '_ {
+        Canvas::default()
+            .block(Block::bordered().title("World"))
+            .marker(self.marker)
+            .paint(|ctx| {
+                ctx.draw(&Map {
+                    color: Color::Green,
+                    resolution: MapResolution::High,
+                });
+                ctx.print(self.x, -self.y, "You are here".yellow());
+            })
+            .x_bounds([-180.0, 180.0])
+            .y_bounds([-90.0, 90.0])
+    }
+
+    fn pong_canvas(&self) -> impl Widget + '_ {
+        Canvas::default()
+            .block(Block::bordered().title("Pong"))
+            .marker(self.marker)
+            .paint(|ctx| {
+                ctx.draw(&self.ball);
+            })
+            .x_bounds([10.0, 210.0])
+            .y_bounds([10.0, 110.0])
+    }
+
+    fn boxes_canvas(&self, area: Rect) -> impl Widget {
+        let left = 0.0;
+        let right = f64::from(area.width);
+        let bottom = 0.0;
+        let top = f64::from(area.height).mul_add(2.0, -4.0);
+        Canvas::default()
+            .block(Block::bordered().title("Rects"))
+            .marker(self.marker)
+            .x_bounds([left, right])
+            .y_bounds([bottom, top])
+            .paint(|ctx| {
+                for i in 0..=11 {
+                    ctx.draw(&Rectangle {
+                        x: f64::from(i * i + 3 * i) / 2.0 + 2.0,
+                        y: 2.0,
+                        width: f64::from(i),
+                        height: f64::from(i),
+                        color: Color::Red,
+                    });
+                    ctx.draw(&Rectangle {
+                        x: f64::from(i * i + 3 * i) / 2.0 + 2.0,
+                        y: 21.0,
+                        width: f64::from(i),
+                        height: f64::from(i),
+                        color: Color::Blue,
+                    });
+                }
+                for i in 0..100 {
+                    if i % 10 != 0 {
+                        ctx.print(f64::from(i) + 1.0, 0.0, format!("{i}", i = i % 10));
+                    }
+                    if i % 2 == 0 && i % 10 != 0 {
+                        ctx.print(0.0, f64::from(i), format!("{i}", i = i % 10));
+                    }
+                }
+            })
+    }
 }
--- a/examples/chart.rs
+++ b/examples/chart.rs
@@ -1,21 +1,38 @@
-extern crate tui;
-extern crate termion;
+//! # [Ratatui] Chart example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md

-mod util;
-use util::*;
+use std::time::{Duration, Instant};

-use std::io;
-use std::thread;
-use std::time;
-use std::sync::mpsc;
+use color_eyre::Result;
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode},
+    layout::{Alignment, Constraint, Layout, Rect},
+    style::{Color, Modifier, Style, Stylize},
+    symbols::{self, Marker},
+    text::Span,
+    widgets::{block::Title, Axis, Block, Chart, Dataset, GraphType, LegendPosition},
+    DefaultTerminal, Frame,
+};

-use termion::event;
-use termion::input::TermRead;
-
-use tui::Terminal;
-use tui::backend::TermionBackend;
-use tui::widgets::{Widget, Block, border, Chart, Axis, Marker, Dataset};
-use tui::style::{Style, Color, Modifier};
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
+}

 struct App {
    signal1: SinSignal,
@@ -25,132 +42,336 @@ struct App {
    window: [f64; 2],
 }

+#[derive(Clone)]
+struct SinSignal {
+    x: f64,
+    interval: f64,
+    period: f64,
+    scale: f64,
+}
+
+impl SinSignal {
+    const fn new(interval: f64, period: f64, scale: f64) -> Self {
+        Self {
+            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)
+    }
+}
+
 impl App {
-    fn new() -> App {
+    fn new() -> Self {
        let mut signal1 = SinSignal::new(0.2, 3.0, 18.0);
        let mut signal2 = SinSignal::new(0.1, 2.0, 10.0);
        let data1 = signal1.by_ref().take(200).collect::<Vec<(f64, f64)>>();
        let data2 = signal2.by_ref().take(200).collect::<Vec<(f64, f64)>>();
-        App {
-            signal1: signal1,
-            data1: data1,
-            signal2: signal2,
-            data2: data2,
+        Self {
+            signal1,
+            data1,
+            signal2,
+            data2,
            window: [0.0, 20.0],
        }
    }

-    fn advance(&mut self) {
-        for _ in 0..5 {
-            self.data1.remove(0);
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        let tick_rate = Duration::from_millis(250);
+        let mut last_tick = Instant::now();
+        loop {
+            terminal.draw(|frame| self.draw(frame))?;
+
+            let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+            if event::poll(timeout)? {
+                if let Event::Key(key) = event::read()? {
+                    if key.code == KeyCode::Char('q') {
+                        return Ok(());
+                    }
+                }
+            }
+            if last_tick.elapsed() >= tick_rate {
+                self.on_tick();
+                last_tick = Instant::now();
+            }
        }
+    }
+
+    fn on_tick(&mut self) {
+        self.data1.drain(0..5);
        self.data1.extend(self.signal1.by_ref().take(5));
-        for _ in 0..10 {
-            self.data2.remove(0);
-        }
+
+        self.data2.drain(0..10);
        self.data2.extend(self.signal2.by_ref().take(10));
+
        self.window[0] += 1.0;
        self.window[1] += 1.0;
    }
-}

-enum Event {
-    Input(event::Key),
-    Tick,
-}
+    fn draw(&self, frame: &mut Frame) {
+        let [top, bottom] = Layout::vertical([Constraint::Fill(1); 2]).areas(frame.area());
+        let [animated_chart, bar_chart] =
+            Layout::horizontal([Constraint::Fill(1), Constraint::Length(29)]).areas(top);
+        let [line_chart, scatter] = Layout::horizontal([Constraint::Fill(1); 2]).areas(bottom);

-fn main() {
-    // Terminal initialization
-    let backend = TermionBackend::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();
-    draw(&mut terminal, &app);
-
-    loop {
-        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);
+        self.render_animated_chart(frame, animated_chart);
+        render_barchart(frame, bar_chart);
+        render_line_chart(frame, line_chart);
+        render_scatter(frame, scatter);
    }

-    terminal.show_cursor().unwrap();
+    fn render_animated_chart(&self, frame: &mut Frame, area: Rect) {
+        let x_labels = vec![
+            Span::styled(
+                format!("{}", self.window[0]),
+                Style::default().add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(format!("{}", (self.window[0] + self.window[1]) / 2.0)),
+            Span::styled(
+                format!("{}", self.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(&self.data1),
+            Dataset::default()
+                .name("data3")
+                .marker(symbols::Marker::Braille)
+                .style(Style::default().fg(Color::Yellow))
+                .data(&self.data2),
+        ];
+
+        let chart = Chart::new(datasets)
+            .block(Block::bordered())
+            .x_axis(
+                Axis::default()
+                    .title("X Axis")
+                    .style(Style::default().fg(Color::Gray))
+                    .labels(x_labels)
+                    .bounds(self.window),
+            )
+            .y_axis(
+                Axis::default()
+                    .title("Y Axis")
+                    .style(Style::default().fg(Color::Gray))
+                    .labels(["-20".bold(), "0".into(), "20".bold()])
+                    .bounds([-20.0, 20.0]),
+            );
+
+        frame.render_widget(chart, area);
+    }
 }

-fn draw(t: &mut Terminal<TermionBackend>, app: &App) {
+fn render_barchart(frame: &mut Frame, bar_chart: Rect) {
+    let dataset = Dataset::default()
+        .marker(symbols::Marker::HalfBlock)
+        .style(Style::new().fg(Color::Blue))
+        .graph_type(GraphType::Bar)
+        // a bell curve
+        .data(&[
+            (0., 0.4),
+            (10., 2.9),
+            (20., 13.5),
+            (30., 41.1),
+            (40., 80.1),
+            (50., 100.0),
+            (60., 80.1),
+            (70., 41.1),
+            (80., 13.5),
+            (90., 2.9),
+            (100., 0.4),
+        ]);

-    let size = t.size().unwrap();
+    let chart = Chart::new(vec![dataset])
+        .block(
+            Block::bordered().title(
+                Title::default()
+                    .content("Bar chart".cyan().bold())
+                    .alignment(Alignment::Center),
+            ),
+        )
+        .x_axis(
+            Axis::default()
+                .style(Style::default().gray())
+                .bounds([0.0, 100.0])
+                .labels(["0".bold(), "50".into(), "100.0".bold()]),
+        )
+        .y_axis(
+            Axis::default()
+                .style(Style::default().gray())
+                .bounds([0.0, 100.0])
+                .labels(["0".bold(), "50".into(), "100.0".bold()]),
+        )
+        .hidden_legend_constraints((Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)));

-    Chart::default()
-        .block(Block::default()
-            .title("Chart")
-            .title_style(Style::default()
-                .fg(Color::Cyan)
-                .modifier(Modifier::Bold))
-            .borders(border::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(t, &size);
-
-    t.draw().unwrap();
+    frame.render_widget(chart, bar_chart);
 }
+
+fn render_line_chart(frame: &mut Frame, area: Rect) {
+    let datasets = vec![Dataset::default()
+        .name("Line from only 2 points".italic())
+        .marker(symbols::Marker::Braille)
+        .style(Style::default().fg(Color::Yellow))
+        .graph_type(GraphType::Line)
+        .data(&[(1., 1.), (4., 4.)])];
+
+    let chart = Chart::new(datasets)
+        .block(
+            Block::bordered().title(
+                Title::default()
+                    .content("Line chart".cyan().bold())
+                    .alignment(Alignment::Center),
+            ),
+        )
+        .x_axis(
+            Axis::default()
+                .title("X Axis")
+                .style(Style::default().gray())
+                .bounds([0.0, 5.0])
+                .labels(["0".bold(), "2.5".into(), "5.0".bold()]),
+        )
+        .y_axis(
+            Axis::default()
+                .title("Y Axis")
+                .style(Style::default().gray())
+                .bounds([0.0, 5.0])
+                .labels(["0".bold(), "2.5".into(), "5.0".bold()]),
+        )
+        .legend_position(Some(LegendPosition::TopLeft))
+        .hidden_legend_constraints((Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)));
+
+    frame.render_widget(chart, area);
+}
+
+fn render_scatter(frame: &mut Frame, area: Rect) {
+    let datasets = vec![
+        Dataset::default()
+            .name("Heavy")
+            .marker(Marker::Dot)
+            .graph_type(GraphType::Scatter)
+            .style(Style::new().yellow())
+            .data(&HEAVY_PAYLOAD_DATA),
+        Dataset::default()
+            .name("Medium".underlined())
+            .marker(Marker::Braille)
+            .graph_type(GraphType::Scatter)
+            .style(Style::new().magenta())
+            .data(&MEDIUM_PAYLOAD_DATA),
+        Dataset::default()
+            .name("Small")
+            .marker(Marker::Dot)
+            .graph_type(GraphType::Scatter)
+            .style(Style::new().cyan())
+            .data(&SMALL_PAYLOAD_DATA),
+    ];
+
+    let chart = Chart::new(datasets)
+        .block(
+            Block::bordered().title(
+                Title::default()
+                    .content("Scatter chart".cyan().bold())
+                    .alignment(Alignment::Center),
+            ),
+        )
+        .x_axis(
+            Axis::default()
+                .title("Year")
+                .bounds([1960., 2020.])
+                .style(Style::default().fg(Color::Gray))
+                .labels(["1960", "1990", "2020"]),
+        )
+        .y_axis(
+            Axis::default()
+                .title("Cost")
+                .bounds([0., 75000.])
+                .style(Style::default().fg(Color::Gray))
+                .labels(["0", "37 500", "75 000"]),
+        )
+        .hidden_legend_constraints((Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)));
+
+    frame.render_widget(chart, area);
+}
+
+// Data from https://ourworldindata.org/space-exploration-satellites
+const HEAVY_PAYLOAD_DATA: [(f64, f64); 9] = [
+    (1965., 8200.),
+    (1967., 5400.),
+    (1981., 65400.),
+    (1989., 30800.),
+    (1997., 10200.),
+    (2004., 11600.),
+    (2014., 4500.),
+    (2016., 7900.),
+    (2018., 1500.),
+];
+
+const MEDIUM_PAYLOAD_DATA: [(f64, f64); 29] = [
+    (1963., 29500.),
+    (1964., 30600.),
+    (1965., 177_900.),
+    (1965., 21000.),
+    (1966., 17900.),
+    (1966., 8400.),
+    (1975., 17500.),
+    (1982., 8300.),
+    (1985., 5100.),
+    (1988., 18300.),
+    (1990., 38800.),
+    (1990., 9900.),
+    (1991., 18700.),
+    (1992., 9100.),
+    (1994., 10500.),
+    (1994., 8500.),
+    (1994., 8700.),
+    (1997., 6200.),
+    (1999., 18000.),
+    (1999., 7600.),
+    (1999., 8900.),
+    (1999., 9600.),
+    (2000., 16000.),
+    (2001., 10000.),
+    (2002., 10400.),
+    (2002., 8100.),
+    (2010., 2600.),
+    (2013., 13600.),
+    (2017., 8000.),
+];
+
+const SMALL_PAYLOAD_DATA: [(f64, f64); 23] = [
+    (1961., 118_500.),
+    (1962., 14900.),
+    (1975., 21400.),
+    (1980., 32800.),
+    (1988., 31100.),
+    (1990., 41100.),
+    (1993., 23600.),
+    (1994., 20600.),
+    (1994., 34600.),
+    (1996., 50600.),
+    (1997., 19200.),
+    (1997., 45800.),
+    (1998., 19100.),
+    (2000., 73100.),
+    (2003., 11200.),
+    (2008., 12600.),
+    (2010., 30500.),
+    (2012., 20000.),
+    (2013., 10600.),
+    (2013., 34500.),
+    (2015., 10600.),
+    (2018., 23100.),
+    (2019., 17300.),
+];
--- a/examples/colors.rs
+++ b/examples/colors.rs
@@ -0,0 +1,255 @@
+//! # [Ratatui] Colors example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+// 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 color_eyre::Result;
+use itertools::Itertools;
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Alignment, Constraint, Layout, Rect},
+    style::{Color, Style, Stylize},
+    text::Line,
+    widgets::{Block, Borders, Paragraph},
+    DefaultTerminal, Frame,
+};
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = run(terminal);
+    ratatui::restore();
+    app_result
+}
+
+fn run(mut terminal: DefaultTerminal) -> Result<()> {
+    loop {
+        terminal.draw(draw)?;
+        if let Event::Key(key) = event::read()? {
+            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                return Ok(());
+            }
+        }
+    }
+}
+
+fn draw(frame: &mut Frame) {
+    let layout = Layout::vertical([
+        Constraint::Length(30),
+        Constraint::Length(17),
+        Constraint::Length(2),
+    ])
+    .split(frame.area());
+
+    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::vertical([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::vertical([Constraint::Length(1); 2])
+        .split(inner)
+        .iter()
+        .flat_map(|area| {
+            Layout::horizontal([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::vertical([Constraint::Length(1); 2])
+        .split(inner)
+        .iter()
+        .flat_map(|area| {
+            Layout::horizontal([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::vertical([
+        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::horizontal([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::horizontal([Constraint::Length(27); 3])
+                .split(*area)
+                .to_vec()
+        })
+        // each with 6 rows
+        .flat_map(|area| {
+            Layout::vertical([Constraint::Length(1); 6])
+                .split(area)
+                .to_vec()
+        })
+        // each with 6 columns
+        .flat_map(|area| {
+            Layout::horizontal([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::new()
+        .borders(Borders::TOP)
+        .title_alignment(Alignment::Center)
+        .border_style(Style::new().dark_gray())
+        .title_style(Style::new().reset())
+        .title(title)
+}
+
+fn render_indexed_grayscale(frame: &mut Frame, area: Rect) {
+    let layout = Layout::vertical([
+        Constraint::Length(1), // 232 - 243
+        Constraint::Length(1), // 244 - 255
+    ])
+    .split(area)
+    .iter()
+    .flat_map(|area| {
+        Layout::horizontal([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]);
+    }
+}
--- a/examples/colors_rgb.rs
+++ b/examples/colors_rgb.rs
@@ -0,0 +1,256 @@
+//! # [Ratatui] `Colors_RGB` example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+// 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.
+//
+// This example also demonstrates how implementing the Widget trait on a mutable reference
+// allows the widget to update its state while it is being rendered. This allows the fps
+// widget to update the fps calculation and the colors widget to update a cached version of
+// the colors to render instead of recalculating them every frame.
+//
+// This is an alternative to using the `StatefulWidget` trait and a separate state struct. It
+// is useful when the state is only used by the widget and doesn't need to be shared with
+// other widgets.
+
+use std::time::{Duration, Instant};
+
+use color_eyre::Result;
+use palette::{convert::FromColorUnclamped, Okhsv, Srgb};
+use ratatui::{
+    buffer::Buffer,
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Constraint, Layout, Position, Rect},
+    style::Color,
+    text::Text,
+    widgets::Widget,
+    DefaultTerminal,
+};
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
+#[derive(Debug, Default)]
+struct App {
+    /// The current state of the app (running or quit)
+    state: AppState,
+
+    /// A widget that displays the current frames per second
+    fps_widget: FpsWidget,
+
+    /// A widget that displays the full range of RGB colors that can be displayed in the terminal.
+    colors_widget: ColorsWidget,
+}
+
+#[derive(Debug, Default, PartialEq, Eq)]
+enum AppState {
+    /// The app is running
+    #[default]
+    Running,
+
+    /// The user has requested the app to quit
+    Quit,
+}
+
+/// A widget that displays the current frames per second
+#[derive(Debug)]
+struct FpsWidget {
+    /// The number of elapsed frames that have passed - used to calculate the fps
+    frame_count: usize,
+
+    /// The last instant that the fps was calculated
+    last_instant: Instant,
+
+    /// The current frames per second
+    fps: Option<f32>,
+}
+
+/// A widget that displays the full range of RGB colors that can be displayed in the terminal.
+///
+/// This widget is animated and will change colors over time.
+#[derive(Debug, Default)]
+struct ColorsWidget {
+    /// The colors to render - should be double the height of the area as we render two rows of
+    /// pixels for each row of the widget using the half block character. This is computed any time
+    /// the size of the widget changes.
+    colors: Vec<Vec<Color>>,
+
+    /// the number of elapsed frames that have passed - used to animate the colors by shifting the
+    /// x index by the frame number
+    frame_count: usize,
+}
+
+impl App {
+    /// Run the app
+    ///
+    /// This is the main event loop for the app.
+    pub fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        while self.is_running() {
+            terminal.draw(|frame| frame.render_widget(&mut self, frame.area()))?;
+            self.handle_events()?;
+        }
+        Ok(())
+    }
+
+    const fn is_running(&self) -> bool {
+        matches!(self.state, AppState::Running)
+    }
+
+    /// Handle any events that have occurred since the last time the app was rendered.
+    ///
+    /// Currently, this only handles the q key to quit the app.
+    fn handle_events(&mut self) -> Result<()> {
+        // Ensure that the app only blocks for a period that allows the app to render at
+        // approximately 60 FPS (this doesn't account for the time to render the frame, and will
+        // also update the app immediately any time an event occurs)
+        let timeout = Duration::from_secs_f32(1.0 / 60.0);
+        if event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                    self.state = AppState::Quit;
+                };
+            }
+        }
+        Ok(())
+    }
+}
+
+/// Implement the Widget trait for &mut App so that it can be rendered
+///
+/// This is implemented on a mutable reference so that the app can update its state while it is
+/// being rendered. This allows the fps widget to update the fps calculation and the colors widget
+/// to update the colors to render.
+impl Widget for &mut App {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        use Constraint::{Length, Min};
+        let [top, colors] = Layout::vertical([Length(1), Min(0)]).areas(area);
+        let [title, fps] = Layout::horizontal([Min(0), Length(8)]).areas(top);
+        Text::from("colors_rgb example. Press q to quit")
+            .centered()
+            .render(title, buf);
+        self.fps_widget.render(fps, buf);
+        self.colors_widget.render(colors, buf);
+    }
+}
+
+/// Default impl for `FpsWidget`
+///
+/// Manual impl is required because we need to initialize the `last_instant` field to the current
+/// instant.
+impl Default for FpsWidget {
+    fn default() -> Self {
+        Self {
+            frame_count: 0,
+            last_instant: Instant::now(),
+            fps: None,
+        }
+    }
+}
+
+/// Widget impl for `FpsWidget`
+///
+/// This is implemented on a mutable reference so that we can update the frame count and fps
+/// calculation while rendering.
+impl Widget for &mut FpsWidget {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        self.calculate_fps();
+        if let Some(fps) = self.fps {
+            let text = format!("{fps:.1} fps");
+            Text::from(text).render(area, buf);
+        }
+    }
+}
+
+impl FpsWidget {
+    /// Update the fps calculation.
+    ///
+    /// This updates the fps once a second, but only if the widget has rendered at least 2 frames
+    /// since the last calculation. This avoids noise in the fps calculation when rendering on slow
+    /// machines that can't render at least 2 frames per second.
+    #[allow(clippy::cast_precision_loss)]
+    fn calculate_fps(&mut self) {
+        self.frame_count += 1;
+        let elapsed = self.last_instant.elapsed();
+        if elapsed > Duration::from_secs(1) && self.frame_count > 2 {
+            self.fps = Some(self.frame_count as f32 / elapsed.as_secs_f32());
+            self.frame_count = 0;
+            self.last_instant = Instant::now();
+        }
+    }
+}
+
+/// Widget impl for `ColorsWidget`
+///
+/// This is implemented on a mutable reference so that we can update the frame count and store a
+/// cached version of the colors to render instead of recalculating them every frame.
+impl Widget for &mut ColorsWidget {
+    /// Render the widget
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        self.setup_colors(area);
+        let colors = &self.colors;
+        for (xi, x) in (area.left()..area.right()).enumerate() {
+            // animate the colors by shifting the x index by the frame number
+            let xi = (xi + self.frame_count) % (area.width as usize);
+            for (yi, y) in (area.top()..area.bottom()).enumerate() {
+                // render a half block character for each row of pixels with the foreground color
+                // set to the color of the pixel and the background color set to the color of the
+                // pixel below it
+                let fg = colors[yi * 2][xi];
+                let bg = colors[yi * 2 + 1][xi];
+                buf[Position::new(x, y)].set_char('▀').set_fg(fg).set_bg(bg);
+            }
+        }
+        self.frame_count += 1;
+    }
+}
+
+impl ColorsWidget {
+    /// Setup the colors to render.
+    ///
+    /// This is called once per frame to setup the colors to render. It caches the colors so that
+    /// they don't need to be recalculated every frame.
+    #[allow(clippy::cast_precision_loss)]
+    fn setup_colors(&mut self, size: Rect) {
+        let Rect { width, height, .. } = size;
+        // double the height because each screen row has two rows of half block pixels
+        let height = height as usize * 2;
+        let width = width as usize;
+        // only update the colors if the size has changed since the last time we rendered
+        if self.colors.len() == height && self.colors[0].len() == width {
+            return;
+        }
+        self.colors = Vec::with_capacity(height);
+        for y in 0..height {
+            let mut row = Vec::with_capacity(width);
+            for x in 0..width {
+                let hue = x as f32 * 360.0 / width as f32;
+                let value = (height - y) as f32 / height as f32;
+                let saturation = Okhsv::max_saturation();
+                let color = Okhsv::new(hue, saturation, value);
+                let color = Srgb::<f32>::from_color_unclamped(color);
+                let color: Srgb<u8> = color.into_format();
+                let color = Color::Rgb(color.red, color.green, color.blue);
+                row.push(color);
+            }
+            self.colors.push(row);
+        }
+    }
+}
--- a/examples/constraint-explorer.rs
+++ b/examples/constraint-explorer.rs
@@ -0,0 +1,611 @@
+//! # [Ratatui] Constraint explorer example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+use color_eyre::Result;
+use itertools::Itertools;
+use ratatui::{
+    buffer::Buffer,
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{
+        Constraint::{self, Fill, Length, Max, Min, Percentage, Ratio},
+        Flex, Layout, Rect,
+    },
+    style::{
+        palette::tailwind::{BLUE, SKY, SLATE, STONE},
+        Color, Style, Stylize,
+    },
+    symbols::{self, line},
+    text::{Line, Span, Text},
+    widgets::{Block, Paragraph, Widget, Wrap},
+    DefaultTerminal,
+};
+use strum::{Display, EnumIter, FromRepr};
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
+#[derive(Default)]
+struct App {
+    mode: AppMode,
+    spacing: u16,
+    constraints: Vec<Constraint>,
+    selected_index: usize,
+    value: u16,
+}
+
+#[derive(Debug, Default, PartialEq, Eq)]
+enum AppMode {
+    #[default]
+    Running,
+    Quit,
+}
+
+/// A variant of [`Constraint`] that can be rendered as a tab.
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, EnumIter, FromRepr, Display)]
+enum ConstraintName {
+    #[default]
+    Length,
+    Percentage,
+    Ratio,
+    Min,
+    Max,
+    Fill,
+}
+
+/// A widget that renders a [`Constraint`] as a block. E.g.:
+/// ```plain
+/// ┌──────────────┐
+/// │  Length(16)  │
+/// │     16px     │
+/// └──────────────┘
+/// ```
+struct ConstraintBlock {
+    constraint: Constraint,
+    legend: bool,
+    selected: bool,
+}
+
+/// A widget that renders a spacer with a label indicating the width of the spacer. E.g.:
+///
+/// ```plain
+/// ┌      ┐
+///   8 px
+/// └      ┘
+/// ```
+struct SpacerBlock;
+
+// App behaviour
+impl App {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        self.insert_test_defaults();
+
+        while self.is_running() {
+            terminal.draw(|frame| frame.render_widget(&self, frame.area()))?;
+            self.handle_events()?;
+        }
+        Ok(())
+    }
+
+    // TODO remove these - these are just for testing
+    fn insert_test_defaults(&mut self) {
+        self.constraints = vec![
+            Constraint::Length(20),
+            Constraint::Length(20),
+            Constraint::Length(20),
+        ];
+        self.value = 20;
+    }
+
+    fn is_running(&self) -> bool {
+        self.mode == AppMode::Running
+    }
+
+    fn handle_events(&mut self) -> Result<()> {
+        match event::read()? {
+            Event::Key(key) if key.kind == KeyEventKind::Press => match key.code {
+                KeyCode::Char('q') | KeyCode::Esc => self.exit(),
+                KeyCode::Char('1') => self.swap_constraint(ConstraintName::Min),
+                KeyCode::Char('2') => self.swap_constraint(ConstraintName::Max),
+                KeyCode::Char('3') => self.swap_constraint(ConstraintName::Length),
+                KeyCode::Char('4') => self.swap_constraint(ConstraintName::Percentage),
+                KeyCode::Char('5') => self.swap_constraint(ConstraintName::Ratio),
+                KeyCode::Char('6') => self.swap_constraint(ConstraintName::Fill),
+                KeyCode::Char('+') => self.increment_spacing(),
+                KeyCode::Char('-') => self.decrement_spacing(),
+                KeyCode::Char('x') => self.delete_block(),
+                KeyCode::Char('a') => self.insert_block(),
+                KeyCode::Char('k') | KeyCode::Up => self.increment_value(),
+                KeyCode::Char('j') | KeyCode::Down => self.decrement_value(),
+                KeyCode::Char('h') | KeyCode::Left => self.prev_block(),
+                KeyCode::Char('l') | KeyCode::Right => self.next_block(),
+                _ => {}
+            },
+            _ => {}
+        }
+        Ok(())
+    }
+
+    fn increment_value(&mut self) {
+        let Some(constraint) = self.constraints.get_mut(self.selected_index) else {
+            return;
+        };
+        match constraint {
+            Constraint::Length(v)
+            | Constraint::Min(v)
+            | Constraint::Max(v)
+            | Constraint::Fill(v)
+            | Constraint::Percentage(v) => *v = v.saturating_add(1),
+            Constraint::Ratio(_n, d) => *d = d.saturating_add(1),
+        };
+    }
+
+    fn decrement_value(&mut self) {
+        let Some(constraint) = self.constraints.get_mut(self.selected_index) else {
+            return;
+        };
+        match constraint {
+            Constraint::Length(v)
+            | Constraint::Min(v)
+            | Constraint::Max(v)
+            | Constraint::Fill(v)
+            | Constraint::Percentage(v) => *v = v.saturating_sub(1),
+            Constraint::Ratio(_n, d) => *d = d.saturating_sub(1),
+        };
+    }
+
+    /// select the next block with wrap around
+    fn next_block(&mut self) {
+        if self.constraints.is_empty() {
+            return;
+        }
+        let len = self.constraints.len();
+        self.selected_index = (self.selected_index + 1) % len;
+    }
+
+    /// select the previous block with wrap around
+    fn prev_block(&mut self) {
+        if self.constraints.is_empty() {
+            return;
+        }
+        let len = self.constraints.len();
+        self.selected_index = (self.selected_index + self.constraints.len() - 1) % len;
+    }
+
+    /// delete the selected block
+    fn delete_block(&mut self) {
+        if self.constraints.is_empty() {
+            return;
+        }
+        self.constraints.remove(self.selected_index);
+        self.selected_index = self.selected_index.saturating_sub(1);
+    }
+
+    /// insert a block after the selected block
+    fn insert_block(&mut self) {
+        let index = self
+            .selected_index
+            .saturating_add(1)
+            .min(self.constraints.len());
+        let constraint = Constraint::Length(self.value);
+        self.constraints.insert(index, constraint);
+        self.selected_index = index;
+    }
+
+    fn increment_spacing(&mut self) {
+        self.spacing = self.spacing.saturating_add(1);
+    }
+
+    fn decrement_spacing(&mut self) {
+        self.spacing = self.spacing.saturating_sub(1);
+    }
+
+    fn exit(&mut self) {
+        self.mode = AppMode::Quit;
+    }
+
+    fn swap_constraint(&mut self, name: ConstraintName) {
+        if self.constraints.is_empty() {
+            return;
+        }
+        let constraint = match name {
+            ConstraintName::Length => Length(self.value),
+            ConstraintName::Percentage => Percentage(self.value),
+            ConstraintName::Min => Min(self.value),
+            ConstraintName::Max => Max(self.value),
+            ConstraintName::Fill => Fill(self.value),
+            ConstraintName::Ratio => Ratio(1, u32::from(self.value) / 4), // for balance
+        };
+        self.constraints[self.selected_index] = constraint;
+    }
+}
+
+impl From<Constraint> for ConstraintName {
+    fn from(constraint: Constraint) -> Self {
+        match constraint {
+            Length(_) => Self::Length,
+            Percentage(_) => Self::Percentage,
+            Ratio(_, _) => Self::Ratio,
+            Min(_) => Self::Min,
+            Max(_) => Self::Max,
+            Fill(_) => Self::Fill,
+        }
+    }
+}
+
+impl Widget for &App {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let [header_area, instructions_area, swap_legend_area, _, blocks_area] =
+            Layout::vertical([
+                Length(2), // header
+                Length(2), // instructions
+                Length(1), // swap key legend
+                Length(1), // gap
+                Fill(1),   // blocks
+            ])
+            .areas(area);
+
+        App::header().render(header_area, buf);
+        App::instructions().render(instructions_area, buf);
+        App::swap_legend().render(swap_legend_area, buf);
+        self.render_layout_blocks(blocks_area, buf);
+    }
+}
+
+// App rendering
+impl App {
+    const HEADER_COLOR: Color = SLATE.c200;
+    const TEXT_COLOR: Color = SLATE.c400;
+    const AXIS_COLOR: Color = SLATE.c500;
+
+    fn header() -> impl Widget {
+        let text = "Constraint Explorer";
+        text.bold().fg(Self::HEADER_COLOR).into_centered_line()
+    }
+
+    fn instructions() -> impl Widget {
+        let text = "◄ ►: select, ▲ ▼: edit, 1-6: swap, a: add, x: delete, q: quit, + -: spacing";
+        Paragraph::new(text)
+            .fg(Self::TEXT_COLOR)
+            .centered()
+            .wrap(Wrap { trim: false })
+    }
+
+    fn swap_legend() -> impl Widget {
+        #[allow(unstable_name_collisions)]
+        Paragraph::new(
+            Line::from(
+                [
+                    ConstraintName::Min,
+                    ConstraintName::Max,
+                    ConstraintName::Length,
+                    ConstraintName::Percentage,
+                    ConstraintName::Ratio,
+                    ConstraintName::Fill,
+                ]
+                .iter()
+                .enumerate()
+                .map(|(i, name)| {
+                    format!("  {i}: {name}  ", i = i + 1)
+                        .fg(SLATE.c200)
+                        .bg(name.color())
+                })
+                .intersperse(Span::from(" "))
+                .collect_vec(),
+            )
+            .centered(),
+        )
+        .wrap(Wrap { trim: false })
+    }
+
+    /// A bar like `<----- 80 px (gap: 2 px) ----->`
+    ///
+    /// Only shows the gap when spacing is not zero
+    fn axis(&self, width: u16) -> impl Widget {
+        let label = if self.spacing != 0 {
+            format!("{} px (gap: {} px)", width, self.spacing)
+        } else {
+            format!("{width} px")
+        };
+        let bar_width = width.saturating_sub(2) as usize; // we want to `<` and `>` at the ends
+        let width_bar = format!("<{label:-^bar_width$}>");
+        Paragraph::new(width_bar).fg(Self::AXIS_COLOR).centered()
+    }
+
+    fn render_layout_blocks(&self, area: Rect, buf: &mut Buffer) {
+        let [user_constraints, area] = Layout::vertical([Length(3), Fill(1)])
+            .spacing(1)
+            .areas(area);
+
+        self.render_user_constraints_legend(user_constraints, buf);
+
+        let [start, center, end, space_around, space_between] =
+            Layout::vertical([Length(7); 5]).areas(area);
+
+        self.render_layout_block(Flex::Start, start, buf);
+        self.render_layout_block(Flex::Center, center, buf);
+        self.render_layout_block(Flex::End, end, buf);
+        self.render_layout_block(Flex::SpaceAround, space_around, buf);
+        self.render_layout_block(Flex::SpaceBetween, space_between, buf);
+    }
+
+    fn render_user_constraints_legend(&self, area: Rect, buf: &mut Buffer) {
+        let blocks = Layout::horizontal(
+            self.constraints
+                .iter()
+                .map(|_| Constraint::Fill(1))
+                .collect_vec(),
+        )
+        .split(area);
+
+        for (i, (area, constraint)) in blocks.iter().zip(self.constraints.iter()).enumerate() {
+            let selected = self.selected_index == i;
+            ConstraintBlock::new(*constraint, selected, true).render(*area, buf);
+        }
+    }
+
+    fn render_layout_block(&self, flex: Flex, area: Rect, buf: &mut Buffer) {
+        let [label_area, axis_area, blocks_area] =
+            Layout::vertical([Length(1), Max(1), Length(4)]).areas(area);
+
+        if label_area.height > 0 {
+            format!("Flex::{flex:?}").bold().render(label_area, buf);
+        }
+
+        self.axis(area.width).render(axis_area, buf);
+
+        let (blocks, spacers) = Layout::horizontal(&self.constraints)
+            .flex(flex)
+            .spacing(self.spacing)
+            .split_with_spacers(blocks_area);
+
+        for (i, (area, constraint)) in blocks.iter().zip(self.constraints.iter()).enumerate() {
+            let selected = self.selected_index == i;
+            ConstraintBlock::new(*constraint, selected, false).render(*area, buf);
+        }
+
+        for area in spacers.iter() {
+            SpacerBlock.render(*area, buf);
+        }
+    }
+}
+
+impl Widget for ConstraintBlock {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        match area.height {
+            1 => self.render_1px(area, buf),
+            2 => self.render_2px(area, buf),
+            _ => self.render_4px(area, buf),
+        }
+    }
+}
+
+impl ConstraintBlock {
+    const TEXT_COLOR: Color = SLATE.c200;
+
+    const fn new(constraint: Constraint, selected: bool, legend: bool) -> Self {
+        Self {
+            constraint,
+            legend,
+            selected,
+        }
+    }
+
+    fn label(&self, width: u16) -> String {
+        let long_width = format!("{width} px");
+        let short_width = format!("{width}");
+        // border takes up 2 columns
+        let available_space = width.saturating_sub(2) as usize;
+        let width_label = if long_width.len() < available_space {
+            long_width
+        } else if short_width.len() < available_space {
+            short_width
+        } else {
+            String::new()
+        };
+        format!("{}\n{}", self.constraint, width_label)
+    }
+
+    fn render_1px(&self, area: Rect, buf: &mut Buffer) {
+        let lighter_color = ConstraintName::from(self.constraint).lighter_color();
+        let main_color = ConstraintName::from(self.constraint).color();
+        let selected_color = if self.selected {
+            lighter_color
+        } else {
+            main_color
+        };
+        Block::new()
+            .fg(Self::TEXT_COLOR)
+            .bg(selected_color)
+            .render(area, buf);
+    }
+
+    fn render_2px(&self, area: Rect, buf: &mut Buffer) {
+        let lighter_color = ConstraintName::from(self.constraint).lighter_color();
+        let main_color = ConstraintName::from(self.constraint).color();
+        let selected_color = if self.selected {
+            lighter_color
+        } else {
+            main_color
+        };
+        Block::bordered()
+            .border_set(symbols::border::QUADRANT_OUTSIDE)
+            .border_style(Style::reset().fg(selected_color).reversed())
+            .render(area, buf);
+    }
+
+    fn render_4px(&self, area: Rect, buf: &mut Buffer) {
+        let lighter_color = ConstraintName::from(self.constraint).lighter_color();
+        let main_color = ConstraintName::from(self.constraint).color();
+        let selected_color = if self.selected {
+            lighter_color
+        } else {
+            main_color
+        };
+        let color = if self.legend {
+            selected_color
+        } else {
+            main_color
+        };
+        let label = self.label(area.width);
+        let block = Block::bordered()
+            .border_set(symbols::border::QUADRANT_OUTSIDE)
+            .border_style(Style::reset().fg(color).reversed())
+            .fg(Self::TEXT_COLOR)
+            .bg(color);
+        Paragraph::new(label)
+            .centered()
+            .fg(Self::TEXT_COLOR)
+            .bg(color)
+            .block(block)
+            .render(area, buf);
+
+        if !self.legend {
+            let border_color = if self.selected {
+                lighter_color
+            } else {
+                main_color
+            };
+            if let Some(last_row) = area.rows().last() {
+                buf.set_style(last_row, border_color);
+            }
+        }
+    }
+}
+
+impl Widget for SpacerBlock {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        match area.height {
+            1 => (),
+            2 => Self::render_2px(area, buf),
+            3 => Self::render_3px(area, buf),
+            _ => Self::render_4px(area, buf),
+        }
+    }
+}
+
+impl SpacerBlock {
+    const TEXT_COLOR: Color = SLATE.c500;
+    const BORDER_COLOR: Color = SLATE.c600;
+
+    /// A block with a corner borders
+    fn block() -> impl Widget {
+        let corners_only = symbols::border::Set {
+            top_left: line::NORMAL.top_left,
+            top_right: line::NORMAL.top_right,
+            bottom_left: line::NORMAL.bottom_left,
+            bottom_right: line::NORMAL.bottom_right,
+            vertical_left: " ",
+            vertical_right: " ",
+            horizontal_top: " ",
+            horizontal_bottom: " ",
+        };
+        Block::bordered()
+            .border_set(corners_only)
+            .border_style(Self::BORDER_COLOR)
+    }
+
+    /// A vertical line used if there is not enough space to render the block
+    fn line() -> impl Widget {
+        Paragraph::new(Text::from(vec![
+            Line::from(""),
+            Line::from("│"),
+            Line::from("│"),
+            Line::from(""),
+        ]))
+        .style(Self::BORDER_COLOR)
+    }
+
+    /// A label that says "Spacer" if there is enough space
+    fn spacer_label(width: u16) -> impl Widget {
+        let label = if width >= 6 { "Spacer" } else { "" };
+        label.fg(Self::TEXT_COLOR).into_centered_line()
+    }
+
+    /// A label that says "8 px" if there is enough space
+    fn label(width: u16) -> impl Widget {
+        let long_label = format!("{width} px");
+        let short_label = format!("{width}");
+        let label = if long_label.len() < width as usize {
+            long_label
+        } else if short_label.len() < width as usize {
+            short_label
+        } else {
+            String::new()
+        };
+        Line::styled(label, Self::TEXT_COLOR).centered()
+    }
+
+    fn render_2px(area: Rect, buf: &mut Buffer) {
+        if area.width > 1 {
+            Self::block().render(area, buf);
+        } else {
+            Self::line().render(area, buf);
+        }
+    }
+
+    fn render_3px(area: Rect, buf: &mut Buffer) {
+        if area.width > 1 {
+            Self::block().render(area, buf);
+        } else {
+            Self::line().render(area, buf);
+        }
+
+        let row = area.rows().nth(1).unwrap_or_default();
+        Self::spacer_label(area.width).render(row, buf);
+    }
+
+    fn render_4px(area: Rect, buf: &mut Buffer) {
+        if area.width > 1 {
+            Self::block().render(area, buf);
+        } else {
+            Self::line().render(area, buf);
+        }
+
+        let row = area.rows().nth(1).unwrap_or_default();
+        Self::spacer_label(area.width).render(row, buf);
+
+        let row = area.rows().nth(2).unwrap_or_default();
+        Self::label(area.width).render(row, buf);
+    }
+}
+
+impl ConstraintName {
+    const fn color(self) -> Color {
+        match self {
+            Self::Length => SLATE.c700,
+            Self::Percentage => SLATE.c800,
+            Self::Ratio => SLATE.c900,
+            Self::Fill => SLATE.c950,
+            Self::Min => BLUE.c800,
+            Self::Max => BLUE.c900,
+        }
+    }
+
+    const fn lighter_color(self) -> Color {
+        match self {
+            Self::Length => STONE.c500,
+            Self::Percentage => STONE.c600,
+            Self::Ratio => STONE.c700,
+            Self::Fill => STONE.c800,
+            Self::Min => SKY.c600,
+            Self::Max => SKY.c700,
+        }
+    }
+}
--- a/examples/constraints.rs
+++ b/examples/constraints.rs
@@ -0,0 +1,405 @@
+//! # [Ratatui] Constraints example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+use color_eyre::Result;
+use ratatui::{
+    buffer::Buffer,
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{
+        Constraint::{self, Fill, Length, Max, Min, Percentage, Ratio},
+        Layout, Rect,
+    },
+    style::{palette::tailwind, Color, Modifier, Style, Stylize},
+    symbols,
+    text::Line,
+    widgets::{
+        Block, Padding, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState, StatefulWidget,
+        Tabs, Widget,
+    },
+    DefaultTerminal,
+};
+use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
+
+const SPACER_HEIGHT: u16 = 0;
+const ILLUSTRATION_HEIGHT: u16 = 4;
+const EXAMPLE_HEIGHT: u16 = ILLUSTRATION_HEIGHT + SPACER_HEIGHT;
+
+// priority 2
+const MIN_COLOR: Color = tailwind::BLUE.c900;
+const MAX_COLOR: Color = tailwind::BLUE.c800;
+// priority 3
+const LENGTH_COLOR: Color = tailwind::SLATE.c700;
+const PERCENTAGE_COLOR: Color = tailwind::SLATE.c800;
+const RATIO_COLOR: Color = tailwind::SLATE.c900;
+// priority 4
+const FILL_COLOR: Color = tailwind::SLATE.c950;
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
+#[derive(Default, Clone, Copy)]
+struct App {
+    selected_tab: SelectedTab,
+    scroll_offset: u16,
+    max_scroll_offset: u16,
+    state: AppState,
+}
+
+/// Tabs for the different examples
+///
+/// The order of the variants is the order in which they are displayed.
+#[derive(Default, Debug, Copy, Clone, Display, FromRepr, EnumIter, PartialEq, Eq)]
+enum SelectedTab {
+    #[default]
+    Min,
+    Max,
+    Length,
+    Percentage,
+    Ratio,
+    Fill,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+enum AppState {
+    #[default]
+    Running,
+    Quit,
+}
+
+impl App {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        self.update_max_scroll_offset();
+        while self.is_running() {
+            terminal.draw(|frame| frame.render_widget(self, frame.area()))?;
+            self.handle_events()?;
+        }
+        Ok(())
+    }
+
+    fn update_max_scroll_offset(&mut self) {
+        self.max_scroll_offset = (self.selected_tab.get_example_count() - 1) * EXAMPLE_HEIGHT;
+    }
+
+    fn is_running(self) -> bool {
+        self.state == AppState::Running
+    }
+
+    fn handle_events(&mut self) -> Result<()> {
+        if let Event::Key(key) = event::read()? {
+            if key.kind != KeyEventKind::Press {
+                return Ok(());
+            }
+            match key.code {
+                KeyCode::Char('q') | KeyCode::Esc => self.quit(),
+                KeyCode::Char('l') | KeyCode::Right => self.next(),
+                KeyCode::Char('h') | KeyCode::Left => self.previous(),
+                KeyCode::Char('j') | KeyCode::Down => self.down(),
+                KeyCode::Char('k') | KeyCode::Up => self.up(),
+                KeyCode::Char('g') | KeyCode::Home => self.top(),
+                KeyCode::Char('G') | KeyCode::End => self.bottom(),
+                _ => (),
+            }
+        }
+        Ok(())
+    }
+
+    fn quit(&mut self) {
+        self.state = AppState::Quit;
+    }
+
+    fn next(&mut self) {
+        self.selected_tab = self.selected_tab.next();
+        self.update_max_scroll_offset();
+        self.scroll_offset = 0;
+    }
+
+    fn previous(&mut self) {
+        self.selected_tab = self.selected_tab.previous();
+        self.update_max_scroll_offset();
+        self.scroll_offset = 0;
+    }
+
+    fn up(&mut self) {
+        self.scroll_offset = self.scroll_offset.saturating_sub(1);
+    }
+
+    fn down(&mut self) {
+        self.scroll_offset = self
+            .scroll_offset
+            .saturating_add(1)
+            .min(self.max_scroll_offset);
+    }
+
+    fn top(&mut self) {
+        self.scroll_offset = 0;
+    }
+
+    fn bottom(&mut self) {
+        self.scroll_offset = self.max_scroll_offset;
+    }
+}
+
+impl Widget for App {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let [tabs, axis, demo] = Layout::vertical([Length(3), Length(3), Fill(0)]).areas(area);
+
+        self.render_tabs(tabs, buf);
+        Self::render_axis(axis, buf);
+        self.render_demo(demo, buf);
+    }
+}
+
+impl App {
+    fn render_tabs(self, area: Rect, buf: &mut Buffer) {
+        let titles = SelectedTab::iter().map(SelectedTab::to_tab_title);
+        let block = Block::new()
+            .title("Constraints ".bold())
+            .title(" Use h l or ◄ ► to change tab and j k or ▲ ▼  to scroll");
+        Tabs::new(titles)
+            .block(block)
+            .highlight_style(Modifier::REVERSED)
+            .select(self.selected_tab as usize)
+            .padding("", "")
+            .divider(" ")
+            .render(area, buf);
+    }
+
+    fn render_axis(area: Rect, buf: &mut Buffer) {
+        let width = area.width as usize;
+        // a bar like `<----- 80 px ----->`
+        let width_label = format!("{width} px");
+        let width_bar = format!(
+            "<{width_label:-^width$}>",
+            width = width - width_label.len() / 2
+        );
+        Paragraph::new(width_bar.dark_gray())
+            .centered()
+            .block(Block::new().padding(Padding {
+                left: 0,
+                right: 0,
+                top: 1,
+                bottom: 0,
+            }))
+            .render(area, buf);
+    }
+
+    /// Render the demo content
+    ///
+    /// This function renders the demo content into a separate buffer and then splices the buffer
+    /// into the main buffer. This is done to make it possible to handle scrolling easily.
+    #[allow(clippy::cast_possible_truncation)]
+    fn render_demo(self, area: Rect, buf: &mut Buffer) {
+        // render demo content into a separate buffer so all examples fit we add an extra
+        // area.height to make sure the last example is fully visible even when the scroll offset is
+        // at the max
+        let height = self.selected_tab.get_example_count() * EXAMPLE_HEIGHT;
+        let demo_area = Rect::new(0, 0, area.width, height + area.height);
+        let mut demo_buf = Buffer::empty(demo_area);
+
+        let scrollbar_needed = self.scroll_offset != 0 || height > area.height;
+        let content_area = if scrollbar_needed {
+            Rect {
+                width: demo_area.width - 1,
+                ..demo_area
+            }
+        } else {
+            demo_area
+        };
+        self.selected_tab.render(content_area, &mut demo_buf);
+
+        let visible_content = demo_buf
+            .content
+            .into_iter()
+            .skip((demo_area.width * self.scroll_offset) as usize)
+            .take(area.area() as usize);
+        for (i, cell) in visible_content.enumerate() {
+            let x = i as u16 % area.width;
+            let y = i as u16 / area.width;
+            buf[(area.x + x, area.y + y)] = cell;
+        }
+
+        if scrollbar_needed {
+            let mut state = ScrollbarState::new(self.max_scroll_offset as usize)
+                .position(self.scroll_offset as usize);
+            Scrollbar::new(ScrollbarOrientation::VerticalRight).render(area, buf, &mut state);
+        }
+    }
+}
+
+impl SelectedTab {
+    /// Get the previous tab, if there is no previous tab return the current tab.
+    fn previous(self) -> Self {
+        let current_index: usize = self as usize;
+        let previous_index = current_index.saturating_sub(1);
+        Self::from_repr(previous_index).unwrap_or(self)
+    }
+
+    /// Get the next tab, if there is no next tab return the current tab.
+    fn next(self) -> Self {
+        let current_index = self as usize;
+        let next_index = current_index.saturating_add(1);
+        Self::from_repr(next_index).unwrap_or(self)
+    }
+
+    const fn get_example_count(self) -> u16 {
+        #[allow(clippy::match_same_arms)]
+        match self {
+            Self::Length => 4,
+            Self::Percentage => 5,
+            Self::Ratio => 4,
+            Self::Fill => 2,
+            Self::Min => 5,
+            Self::Max => 5,
+        }
+    }
+
+    fn to_tab_title(value: Self) -> Line<'static> {
+        let text = format!("  {value}  ");
+        let color = match value {
+            Self::Length => LENGTH_COLOR,
+            Self::Percentage => PERCENTAGE_COLOR,
+            Self::Ratio => RATIO_COLOR,
+            Self::Fill => FILL_COLOR,
+            Self::Min => MIN_COLOR,
+            Self::Max => MAX_COLOR,
+        };
+        text.fg(tailwind::SLATE.c200).bg(color).into()
+    }
+}
+
+impl Widget for SelectedTab {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        match self {
+            Self::Length => Self::render_length_example(area, buf),
+            Self::Percentage => Self::render_percentage_example(area, buf),
+            Self::Ratio => Self::render_ratio_example(area, buf),
+            Self::Fill => Self::render_fill_example(area, buf),
+            Self::Min => Self::render_min_example(area, buf),
+            Self::Max => Self::render_max_example(area, buf),
+        }
+    }
+}
+
+impl SelectedTab {
+    fn render_length_example(area: Rect, buf: &mut Buffer) {
+        let [example1, example2, example3, _] =
+            Layout::vertical([Length(EXAMPLE_HEIGHT); 4]).areas(area);
+
+        Example::new(&[Length(20), Length(20)]).render(example1, buf);
+        Example::new(&[Length(20), Min(20)]).render(example2, buf);
+        Example::new(&[Length(20), Max(20)]).render(example3, buf);
+    }
+
+    fn render_percentage_example(area: Rect, buf: &mut Buffer) {
+        let [example1, example2, example3, example4, example5, _] =
+            Layout::vertical([Length(EXAMPLE_HEIGHT); 6]).areas(area);
+
+        Example::new(&[Percentage(75), Fill(0)]).render(example1, buf);
+        Example::new(&[Percentage(25), Fill(0)]).render(example2, buf);
+        Example::new(&[Percentage(50), Min(20)]).render(example3, buf);
+        Example::new(&[Percentage(0), Max(0)]).render(example4, buf);
+        Example::new(&[Percentage(0), Fill(0)]).render(example5, buf);
+    }
+
+    fn render_ratio_example(area: Rect, buf: &mut Buffer) {
+        let [example1, example2, example3, example4, _] =
+            Layout::vertical([Length(EXAMPLE_HEIGHT); 5]).areas(area);
+
+        Example::new(&[Ratio(1, 2); 2]).render(example1, buf);
+        Example::new(&[Ratio(1, 4); 4]).render(example2, buf);
+        Example::new(&[Ratio(1, 2), Ratio(1, 3), Ratio(1, 4)]).render(example3, buf);
+        Example::new(&[Ratio(1, 2), Percentage(25), Length(10)]).render(example4, buf);
+    }
+
+    fn render_fill_example(area: Rect, buf: &mut Buffer) {
+        let [example1, example2, _] = Layout::vertical([Length(EXAMPLE_HEIGHT); 3]).areas(area);
+
+        Example::new(&[Fill(1), Fill(2), Fill(3)]).render(example1, buf);
+        Example::new(&[Fill(1), Percentage(50), Fill(1)]).render(example2, buf);
+    }
+
+    fn render_min_example(area: Rect, buf: &mut Buffer) {
+        let [example1, example2, example3, example4, example5, _] =
+            Layout::vertical([Length(EXAMPLE_HEIGHT); 6]).areas(area);
+
+        Example::new(&[Percentage(100), Min(0)]).render(example1, buf);
+        Example::new(&[Percentage(100), Min(20)]).render(example2, buf);
+        Example::new(&[Percentage(100), Min(40)]).render(example3, buf);
+        Example::new(&[Percentage(100), Min(60)]).render(example4, buf);
+        Example::new(&[Percentage(100), Min(80)]).render(example5, buf);
+    }
+
+    fn render_max_example(area: Rect, buf: &mut Buffer) {
+        let [example1, example2, example3, example4, example5, _] =
+            Layout::vertical([Length(EXAMPLE_HEIGHT); 6]).areas(area);
+
+        Example::new(&[Percentage(0), Max(0)]).render(example1, buf);
+        Example::new(&[Percentage(0), Max(20)]).render(example2, buf);
+        Example::new(&[Percentage(0), Max(40)]).render(example3, buf);
+        Example::new(&[Percentage(0), Max(60)]).render(example4, buf);
+        Example::new(&[Percentage(0), Max(80)]).render(example5, buf);
+    }
+}
+
+struct Example {
+    constraints: Vec<Constraint>,
+}
+
+impl Example {
+    fn new(constraints: &[Constraint]) -> Self {
+        Self {
+            constraints: constraints.into(),
+        }
+    }
+}
+
+impl Widget for Example {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let [area, _] =
+            Layout::vertical([Length(ILLUSTRATION_HEIGHT), Length(SPACER_HEIGHT)]).areas(area);
+        let blocks = Layout::horizontal(&self.constraints).split(area);
+
+        for (block, constraint) in blocks.iter().zip(&self.constraints) {
+            Self::illustration(*constraint, block.width).render(*block, buf);
+        }
+    }
+}
+
+impl Example {
+    fn illustration(constraint: Constraint, width: u16) -> impl Widget {
+        let color = match constraint {
+            Constraint::Length(_) => LENGTH_COLOR,
+            Constraint::Percentage(_) => PERCENTAGE_COLOR,
+            Constraint::Ratio(_, _) => RATIO_COLOR,
+            Constraint::Fill(_) => FILL_COLOR,
+            Constraint::Min(_) => MIN_COLOR,
+            Constraint::Max(_) => MAX_COLOR,
+        };
+        let fg = Color::White;
+        let title = format!("{constraint}");
+        let content = format!("{width} px");
+        let text = format!("{title}\n{content}");
+        let block = Block::bordered()
+            .border_set(symbols::border::QUADRANT_OUTSIDE)
+            .border_style(Style::reset().fg(color).reversed())
+            .style(Style::default().fg(fg).bg(color));
+        Paragraph::new(text).centered().block(block)
+    }
+}
--- a/examples/custom_widget.rs
+++ b/examples/custom_widget.rs
@@ -1,39 +1,274 @@
-extern crate tui;
+//! # [Ratatui] Custom Widget example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md

-use tui::Terminal;
-use tui::backend::TermionBackend;
-use tui::widgets::Widget;
-use tui::buffer::Buffer;
-use tui::layout::Rect;
-use tui::style::Style;
+use std::{io::stdout, ops::ControlFlow, time::Duration};

-struct Label<'a> {
-    text: &'a str,
-}
+use color_eyre::Result;
+use ratatui::{
+    buffer::Buffer,
+    crossterm::{
+        event::{
+            self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, MouseButton, MouseEvent,
+            MouseEventKind,
+        },
+        execute,
+    },
+    layout::{Constraint, Layout, Rect},
+    style::{Color, Style},
+    text::Line,
+    widgets::{Paragraph, Widget},
+    DefaultTerminal, Frame,
+};

-impl<'a> Default for Label<'a> {
-    fn default() -> Label<'a> {
-        Label { text: "" }
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    execute!(stdout(), EnableMouseCapture)?;
+    let app_result = run(terminal);
+    ratatui::restore();
+    if let Err(err) = execute!(stdout(), DisableMouseCapture) {
+        eprintln!("Error disabling mouse capture: {err}");
    }
+    app_result
 }

-impl<'a> Widget for Label<'a> {
-    fn draw(&self, area: &Rect, buf: &mut Buffer) {
-        buf.set_string(area.left(), area.top(), self.text, &Style::default());
+/// 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,
+}
+
+#[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) -> Self {
+        Button {
+            label: label.into(),
+            theme: BLUE,
+            state: State::Normal,
+        }
    }
-}

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

-fn main() {
-    let mut terminal = Terminal::new(TermionBackend::new().unwrap()).unwrap();
-    let size = terminal.size().unwrap();
-    terminal.clear().unwrap();
-    Label::default().text("Test").render(&mut terminal, &size);
-    terminal.draw().unwrap();
+impl<'a> Widget for Button<'a> {
+    #[allow(clippy::cast_possible_truncation)]
+    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<'_> {
+    const 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 run(mut terminal: DefaultTerminal) -> Result<()> {
+    let mut selected_button: usize = 0;
+    let mut button_states = [State::Selected, State::Normal, State::Normal];
+    loop {
+        terminal.draw(|frame| draw(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, &mut button_states, &mut selected_button).is_break() {
+                    break;
+                }
+            }
+            Event::Mouse(mouse) => {
+                handle_mouse_event(mouse, &mut button_states, &mut selected_button);
+            }
+            _ => (),
+        }
+    }
+    Ok(())
+}
+
+fn draw(frame: &mut Frame, states: [State; 3]) {
+    let vertical = Layout::vertical([
+        Constraint::Length(1),
+        Constraint::Max(3),
+        Constraint::Length(1),
+        Constraint::Min(0), // ignore remaining space
+    ]);
+    let [title, buttons, help, _] = vertical.areas(frame.area());
+
+    frame.render_widget(
+        Paragraph::new("Custom Widget Example (mouse enabled)"),
+        title,
+    );
+    render_buttons(frame, buttons, states);
+    frame.render_widget(Paragraph::new("←/→: select, Space: toggle, q: quit"), help);
+}
+
+fn render_buttons(frame: &mut Frame<'_>, area: Rect, states: [State; 3]) {
+    let horizontal = Layout::horizontal([
+        Constraint::Length(15),
+        Constraint::Length(15),
+        Constraint::Length(15),
+        Constraint::Min(0), // ignore remaining space
+    ]);
+    let [red, green, blue, _] = horizontal.areas(area);
+
+    frame.render_widget(Button::new("Red").theme(RED).state(states[0]), red);
+    frame.render_widget(Button::new("Green").theme(GREEN).state(states[1]), green);
+    frame.render_widget(Button::new("Blue").theme(BLUE).state(states[2]), blue);
+}
+
+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 | KeyCode::Char('h') => {
+            button_states[*selected_button] = State::Normal;
+            *selected_button = selected_button.saturating_sub(1);
+            button_states[*selected_button] = State::Selected;
+        }
+        KeyCode::Right | KeyCode::Char('l') => {
+            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/demo.rs
+++ b/examples/demo.rs
@@ -1,486 +0,0 @@
-#[macro_use]
-extern crate log;
-
-extern crate tui;
-extern crate termion;
-
-mod util;
-
-use std::io;
-use std::thread;
-use std::env;
-use std::time;
-use std::sync::mpsc;
-
-use termion::event;
-use termion::input::TermRead;
-
-use tui::Terminal;
-use tui::backend::TermionBackend;
-use tui::widgets::{Widget, Block, SelectableList, List, Gauge, Sparkline, Paragraph, border,
-                   Chart, Axis, Dataset, BarChart, Marker, Tabs, Table};
-use tui::widgets::canvas::{Canvas, Map, MapResolution, Line};
-use tui::layout::{Group, Direction, Size, Rect};
-use tui::style::{Style, Color, Modifier};
-
-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() {
-
-
-    for argument in env::args() {
-        if argument == "--log" {
-            setup_log("demo.log");
-        }
-    }
-
-    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(200));
-        }
-    });
-
-    let backend = TermionBackend::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();
-}
-
-fn draw(t: &mut Terminal<TermionBackend>, app: &App) -> Result<(), io::Error> {
-
-    Group::default()
-        .direction(Direction::Vertical)
-        .sizes(&[Size::Fixed(3), Size::Min(0)])
-        .render(t, &app.size, |t, chunks| {
-            Tabs::default()
-                .block(Block::default().borders(border::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(t, &chunks[0]);
-            match app.tabs.selection {
-                0 => {
-                    draw_first_tab(t, app, &chunks[1]);
-                }
-                1 => {
-                    draw_second_tab(t, app, &chunks[1]);
-                }
-                _ => {}
-            };
-        });
-    try!(t.draw());
-    Ok(())
-}
-
-fn draw_first_tab(t: &mut Terminal<TermionBackend>, app: &App, area: &Rect) {
-    Group::default()
-        .direction(Direction::Vertical)
-        .sizes(&[Size::Fixed(7), Size::Min(7), Size::Fixed(7)])
-        .render(t, area, |t, chunks| {
-            Block::default()
-                .borders(border::ALL)
-                .title("Graphs")
-                .render(t, &chunks[0]);
-            Group::default()
-                .direction(Direction::Vertical)
-                .margin(1)
-                .sizes(&[Size::Fixed(2), Size::Fixed(3)])
-                .render(t, &chunks[0], |t, chunks| {
-                    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(t, &chunks[0]);
-                    Sparkline::default()
-                        .block(Block::default().title("Sparkline:"))
-                        .style(Style::default().fg(Color::Green))
-                        .data(&app.data)
-                        .render(t, &chunks[1]);
-                });
-            let sizes = if app.show_chart {
-                vec![Size::Percent(50), Size::Percent(50)]
-            } else {
-                vec![Size::Percent(100)]
-            };
-            Group::default()
-                .direction(Direction::Horizontal)
-                .sizes(&sizes)
-                .render(t, &chunks[1], |t, chunks| {
-                    Group::default()
-                        .direction(Direction::Vertical)
-                        .sizes(&[Size::Percent(50), Size::Percent(50)])
-                        .render(t, &chunks[0], |t, chunks| {
-                            Group::default()
-                                .direction(Direction::Horizontal)
-                                .sizes(&[Size::Percent(50), Size::Percent(50)])
-                                .render(t, &chunks[0], |t, chunks| {
-                                    SelectableList::default()
-                                        .block(Block::default()
-                                            .borders(border::ALL)
-                                            .title("List"))
-                                        .items(&app.items)
-                                        .select(app.selected)
-                                        .highlight_style(Style::default().fg(Color::Yellow).modifier(Modifier::Bold))
-                                        .highlight_symbol(">")
-                                        .render(t, &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);
-                                    List::default()
-                                        .block(Block::default()
-                                            .borders(border::ALL)
-                                            .title("List"))
-                                        .items(&app.events.iter().map(|&(evt, level)| (format!("{}: {}", level, evt), match level {
-                                            "ERROR" => &error_style,
-                                            "CRITICAL" => &critical_style,
-                                            "WARNING" => &warning_style,
-                                            _ => &info_style,
-                                        })).collect::<Vec<(String, &Style)>>())
-                                        .render(t, &chunks[1]);
-                                });
-                            BarChart::default()
-                                .block(Block::default()
-                                    .borders(border::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(t, &chunks[1]);
-                        });
-                    if app.show_chart {
-                        Chart::default()
-                            .block(Block::default()
-                                   .title("Chart")
-                                   .title_style(Style::default()
-                                                .fg(Color::Cyan)
-                                                .modifier(Modifier::Bold))
-                                   .borders(border::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(t, &chunks[1]);
-                    }
-                });
-            Paragraph::default()
-                .block(Block::default()
-                       .borders(border::ALL)
-                       .title("Footer")
-                       .title_style(Style::default().fg(Color::Magenta).modifier(Modifier::Bold)))
-                .wrap(true)
-                .text("This is a paragraph with several lines.\nYou can change the color.\nUse \
-                       \\{fg=[color];bg=[color];mod=[modifier] [text]} to highlight the text with a color. For example, {fg=red \
-                       u}{fg=green n}{fg=yellow d}{fg=magenta e}{fg=cyan r} {fg=gray t}{fg=light_gray h}{fg=light_red \
-                       e} {fg=light_green r}{fg=light_yellow a}{fg=light_magenta i}{fg=light_cyan n}{fg=white \
-                       b}{fg=red o}{fg=green w}.\nOh, and if you didn't {mod=italic notice} you can {mod=bold automatically} \
-                       {mod=invert wrap} your {mod=underline text} =).\nOne more thing is that it should display unicode \
-                       characters properly: 日本国, ٩(-̮̮̃-̃)۶ ٩(●̮̮̃•̃)۶ ٩(͡๏̯͡๏)۶ ٩(-̮̮̃•̃).")
-                .render(t, &chunks[2]);
-        });
-}
-
-fn draw_second_tab(t: &mut Terminal<TermionBackend>, app: &App, area: &Rect) {
-    Group::default()
-        .direction(Direction::Horizontal)
-        .sizes(&[Size::Percent(30), Size::Percent(70)])
-        .render(t, area, |t, chunks| {
-            let up_style = Style::default().fg(Color::Green);
-            let failure_style = Style::default().fg(Color::Red);
-            Table::default()
-                .block(Block::default()
-                    .title("Servers")
-                    .borders(border::ALL))
-                .header(&["Server", "Location", "Status"])
-                .header_style(Style::default().fg(Color::Yellow))
-                .widths(&[15, 15, 10])
-                .rows(&app.servers
-                    .iter()
-                    .map(|s| {
-                        (vec![s.name, s.location, s.status],
-                         if s.status == "Up" {
-                            &up_style
-                        } else {
-                            &failure_style
-                        })
-                    })
-                    .collect::<Vec<(Vec<&str>, &Style)>>())
-                .render(t, &chunks[0]);
-
-            Canvas::default()
-                .block(Block::default().title("World").borders(border::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(t, &chunks[1]);
-        })
-}
--- a/examples/demo/app.rs
+++ b/examples/demo/app.rs
@@ -0,0 +1,346 @@
+use rand::{
+    distributions::{Distribution, Uniform},
+    rngs::ThreadRng,
+};
+use ratatui::widgets::ListState;
+
+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) -> Self {
+        Self {
+            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 const fn new(interval: f64, period: f64, scale: f64) -> Self {
+        Self {
+            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>) -> Self {
+        Self { 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>) -> Self {
+        Self {
+            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) {
+        self.points.drain(0..self.tick_rate);
+        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) -> Self {
+        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,79 @@
+use std::{
+    error::Error,
+    io,
+    time::{Duration, Instant},
+};
+
+use ratatui::{
+    backend::{Backend, CrosstermBackend},
+    crossterm::{
+        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    Terminal,
+};
+
+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 app_result = 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) = app_result {
+        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(|frame| ui::draw(frame, &mut app))?;
+
+        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+        if event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                if key.kind == KeyEventKind::Press {
+                    match key.code {
+                        KeyCode::Left | KeyCode::Char('h') => app.on_left(),
+                        KeyCode::Up | KeyCode::Char('k') => app.on_up(),
+                        KeyCode::Right | KeyCode::Char('l') => app.on_right(),
+                        KeyCode::Down | KeyCode::Char('j') => app.on_down(),
+                        KeyCode::Char(c) => app.on_key(c),
+                        _ => {}
+                    }
+                }
+            }
+        }
+        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,55 @@
+//! # [Ratatui] Original Demo example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+use std::{error::Error, time::Duration};
+
+use argh::FromArgs;
+
+mod app;
+#[cfg(feature = "crossterm")]
+mod crossterm;
+#[cfg(all(not(windows), 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(all(not(windows), feature = "termion", not(feature = "crossterm")))]
+    crate::termion::run(tick_rate, cli.enhanced_graphics)?;
+    #[cfg(all(
+        feature = "termwiz",
+        not(feature = "crossterm"),
+        not(feature = "termion")
+    ))]
+    crate::termwiz::run(tick_rate, cli.enhanced_graphics)?;
+    Ok(())
+}
--- a/examples/demo/termion.rs
+++ b/examples/demo/termion.rs
@@ -0,0 +1,86 @@
+#![allow(dead_code)]
+use std::{error::Error, io, sync::mpsc, thread, time::Duration};
+
+use ratatui::{
+    backend::{Backend, TermionBackend},
+    termion::{
+        event::Key,
+        input::{MouseTerminal, TermRead},
+        raw::IntoRawMode,
+        screen::IntoAlternateScreen,
+    },
+    Terminal,
+};
+
+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(|frame| ui::draw(frame, &mut app))?;
+
+        match events.recv()? {
+            Event::Input(key) => match key {
+                Key::Up | Key::Char('k') => app.on_up(),
+                Key::Down | Key::Char('j') => app.on_down(),
+                Key::Left | Key::Char('h') => app.on_left(),
+                Key::Right | Key::Char('l') => app.on_right(),
+                Key::Char(c) => app.on_key(c),
+                _ => {}
+            },
+            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,80 @@
+#![allow(dead_code)]
+use std::{
+    error::Error,
+    time::{Duration, Instant},
+};
+
+use ratatui::{
+    backend::TermwizBackend,
+    termwiz::{
+        input::{InputEvent, KeyCode},
+        terminal::Terminal as TermwizTerminal,
+    },
+    Terminal,
+};
+
+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 app_result = run_app(&mut terminal, app, tick_rate);
+
+    terminal.show_cursor()?;
+    terminal.flush()?;
+
+    if let Err(err) = app_result {
+        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(|frame| ui::draw(frame, &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 | KeyCode::Char('k') => app.on_up(),
+                    KeyCode::DownArrow | KeyCode::Char('j') => app.on_down(),
+                    KeyCode::LeftArrow | KeyCode::Char('h') => app.on_left(),
+                    KeyCode::RightArrow | KeyCode::Char('l') => 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,400 @@
+use ratatui::{
+    layout::{Constraint, Layout, Rect},
+    style::{Color, Modifier, Style},
+    symbols,
+    text::{self, Span},
+    widgets::{
+        canvas::{self, Canvas, Circle, Map, MapResolution, Rectangle},
+        Axis, BarChart, Block, Cell, Chart, Dataset, Gauge, LineGauge, List, ListItem, Paragraph,
+        Row, Sparkline, Table, Tabs, Wrap,
+    },
+    Frame,
+};
+
+use crate::app::App;
+
+pub fn draw(frame: &mut Frame, app: &mut App) {
+    let chunks = Layout::vertical([Constraint::Length(3), Constraint::Min(0)]).split(frame.area());
+    let tabs = app
+        .tabs
+        .titles
+        .iter()
+        .map(|t| text::Line::from(Span::styled(*t, Style::default().fg(Color::Green))))
+        .collect::<Tabs>()
+        .block(Block::bordered().title(app.title))
+        .highlight_style(Style::default().fg(Color::Yellow))
+        .select(app.tabs.index);
+    frame.render_widget(tabs, chunks[0]);
+    match app.tabs.index {
+        0 => draw_first_tab(frame, app, chunks[1]),
+        1 => draw_second_tab(frame, app, chunks[1]),
+        2 => draw_third_tab(frame, app, chunks[1]),
+        _ => {}
+    };
+}
+
+fn draw_first_tab(frame: &mut Frame, app: &mut App, area: Rect) {
+    let chunks = Layout::vertical([
+        Constraint::Length(9),
+        Constraint::Min(8),
+        Constraint::Length(7),
+    ])
+    .split(area);
+    draw_gauges(frame, app, chunks[0]);
+    draw_charts(frame, app, chunks[1]);
+    draw_text(frame, chunks[2]);
+}
+
+fn draw_gauges(frame: &mut Frame, app: &mut App, area: Rect) {
+    let chunks = Layout::vertical([
+        Constraint::Length(2),
+        Constraint::Length(3),
+        Constraint::Length(2),
+    ])
+    .margin(1)
+    .split(area);
+    let block = Block::bordered().title("Graphs");
+    frame.render_widget(block, area);
+
+    let label = format!("{:.2}%", app.progress * 100.0);
+    let gauge = Gauge::default()
+        .block(Block::new().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);
+    frame.render_widget(gauge, chunks[0]);
+
+    let sparkline = Sparkline::default()
+        .block(Block::new().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
+        });
+    frame.render_widget(sparkline, chunks[1]);
+
+    let line_gauge = LineGauge::default()
+        .block(Block::new().title("LineGauge:"))
+        .filled_style(Style::default().fg(Color::Magenta))
+        .line_set(if app.enhanced_graphics {
+            symbols::line::THICK
+        } else {
+            symbols::line::NORMAL
+        })
+        .ratio(app.progress);
+    frame.render_widget(line_gauge, chunks[2]);
+}
+
+#[allow(clippy::too_many_lines)]
+fn draw_charts(frame: &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::horizontal(constraints).split(area);
+    {
+        let chunks = Layout::vertical([Constraint::Percentage(50), Constraint::Percentage(50)])
+            .split(chunks[0]);
+        {
+            let chunks =
+                Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)])
+                    .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::bordered().title("List"))
+                .highlight_style(Style::default().add_modifier(Modifier::BOLD))
+                .highlight_symbol("> ");
+            frame.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::bordered().title("List"));
+            frame.render_stateful_widget(logs, chunks[1], &mut app.logs.state);
+        }
+
+        let barchart = BarChart::default()
+            .block(Block::bordered().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));
+        frame.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::bordered().title(Span::styled(
+                    "Chart",
+                    Style::default()
+                        .fg(Color::Cyan)
+                        .add_modifier(Modifier::BOLD),
+                )),
+            )
+            .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([
+                        Span::styled("-20", Style::default().add_modifier(Modifier::BOLD)),
+                        Span::raw("0"),
+                        Span::styled("20", Style::default().add_modifier(Modifier::BOLD)),
+                    ]),
+            );
+        frame.render_widget(chart, chunks[1]);
+    }
+}
+
+fn draw_text(frame: &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::bordered().title(Span::styled(
+        "Footer",
+        Style::default()
+            .fg(Color::Magenta)
+            .add_modifier(Modifier::BOLD),
+    ));
+    let paragraph = Paragraph::new(text).block(block).wrap(Wrap { trim: true });
+    frame.render_widget(paragraph, area);
+}
+
+fn draw_second_tab(frame: &mut Frame, app: &mut App, area: Rect) {
+    let chunks =
+        Layout::horizontal([Constraint::Percentage(30), Constraint::Percentage(70)]).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,
+        [
+            Constraint::Length(15),
+            Constraint::Length(15),
+            Constraint::Length(10),
+        ],
+    )
+    .header(
+        Row::new(vec!["Server", "Location", "Status"])
+            .style(Style::default().fg(Color::Yellow))
+            .bottom_margin(1),
+    )
+    .block(Block::bordered().title("Servers"));
+    frame.render_widget(table, chunks[0]);
+
+    let map = Canvas::default()
+        .block(Block::bordered().title("World"))
+        .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]);
+    frame.render_widget(map, chunks[1]);
+}
+
+fn draw_third_tab(frame: &mut Frame, _app: &mut App, area: Rect) {
+    let chunks = Layout::horizontal([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,
+        [
+            Constraint::Ratio(1, 3),
+            Constraint::Ratio(1, 3),
+            Constraint::Ratio(1, 3),
+        ],
+    )
+    .block(Block::bordered().title("Colors"));
+    frame.render_widget(table, chunks[0]);
+}
--- a/examples/demo2/app.rs
+++ b/examples/demo2/app.rs
@@ -0,0 +1,225 @@
+use std::time::Duration;
+
+use color_eyre::{eyre::Context, Result};
+use crossterm::event;
+use itertools::Itertools;
+use ratatui::{
+    buffer::Buffer,
+    crossterm::event::{Event, KeyCode, KeyEvent, KeyEventKind},
+    layout::{Constraint, Layout, Rect},
+    style::Color,
+    text::{Line, Span},
+    widgets::{Block, Tabs, Widget},
+    DefaultTerminal, Frame,
+};
+use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
+
+use crate::{
+    destroy,
+    tabs::{AboutTab, EmailTab, RecipeTab, TracerouteTab, WeatherTab},
+    THEME,
+};
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+pub struct App {
+    mode: Mode,
+    tab: Tab,
+    about_tab: AboutTab,
+    recipe_tab: RecipeTab,
+    email_tab: EmailTab,
+    traceroute_tab: TracerouteTab,
+    weather_tab: WeatherTab,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+enum Mode {
+    #[default]
+    Running,
+    Destroy,
+    Quit,
+}
+
+#[derive(Debug, Clone, Copy, Default, Display, EnumIter, FromRepr, PartialEq, Eq)]
+enum Tab {
+    #[default]
+    About,
+    Recipe,
+    Email,
+    Traceroute,
+    Weather,
+}
+
+impl App {
+    /// Run the app until the user quits.
+    pub fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        while self.is_running() {
+            terminal
+                .draw(|frame| self.draw(frame))
+                .wrap_err("terminal.draw")?;
+            self.handle_events()?;
+        }
+        Ok(())
+    }
+
+    fn is_running(&self) -> bool {
+        self.mode != Mode::Quit
+    }
+
+    /// Draw a single frame of the app.
+    fn draw(&self, frame: &mut Frame) {
+        frame.render_widget(self, frame.area());
+        if self.mode == Mode::Destroy {
+            destroy::destroy(frame);
+        }
+    }
+
+    /// Handle events from the terminal.
+    ///
+    /// This function is called once per frame, The events are polled from the stdin with timeout of
+    /// 1/50th of a second. This was chosen to try to match the default frame rate of a GIF in VHS.
+    fn handle_events(&mut self) -> Result<()> {
+        let timeout = Duration::from_secs_f64(1.0 / 50.0);
+        if !event::poll(timeout)? {
+            return Ok(());
+        }
+        match event::read()? {
+            Event::Key(key) if key.kind == KeyEventKind::Press => self.handle_key_press(key),
+            _ => {}
+        }
+        Ok(())
+    }
+
+    fn handle_key_press(&mut self, key: KeyEvent) {
+        match key.code {
+            KeyCode::Char('q') | KeyCode::Esc => self.mode = Mode::Quit,
+            KeyCode::Char('h') | KeyCode::Left => self.prev_tab(),
+            KeyCode::Char('l') | KeyCode::Right => self.next_tab(),
+            KeyCode::Char('k') | KeyCode::Up => self.prev(),
+            KeyCode::Char('j') | KeyCode::Down => self.next(),
+            KeyCode::Char('d') | KeyCode::Delete => self.destroy(),
+            _ => {}
+        };
+    }
+
+    fn prev(&mut self) {
+        match self.tab {
+            Tab::About => self.about_tab.prev_row(),
+            Tab::Recipe => self.recipe_tab.prev(),
+            Tab::Email => self.email_tab.prev(),
+            Tab::Traceroute => self.traceroute_tab.prev_row(),
+            Tab::Weather => self.weather_tab.prev(),
+        }
+    }
+
+    fn next(&mut self) {
+        match self.tab {
+            Tab::About => self.about_tab.next_row(),
+            Tab::Recipe => self.recipe_tab.next(),
+            Tab::Email => self.email_tab.next(),
+            Tab::Traceroute => self.traceroute_tab.next_row(),
+            Tab::Weather => self.weather_tab.next(),
+        }
+    }
+
+    fn prev_tab(&mut self) {
+        self.tab = self.tab.prev();
+    }
+
+    fn next_tab(&mut self) {
+        self.tab = self.tab.next();
+    }
+
+    fn destroy(&mut self) {
+        self.mode = Mode::Destroy;
+    }
+}
+
+/// Implement Widget for &App rather than for App as we would otherwise have to clone or copy the
+/// entire app state on every frame. For this example, the app state is small enough that it doesn't
+/// matter, but for larger apps this can be a significant performance improvement.
+impl Widget for &App {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let vertical = Layout::vertical([
+            Constraint::Length(1),
+            Constraint::Min(0),
+            Constraint::Length(1),
+        ]);
+        let [title_bar, tab, bottom_bar] = vertical.areas(area);
+
+        Block::new().style(THEME.root).render(area, buf);
+        self.render_title_bar(title_bar, buf);
+        self.render_selected_tab(tab, buf);
+        App::render_bottom_bar(bottom_bar, buf);
+    }
+}
+
+impl App {
+    fn render_title_bar(&self, area: Rect, buf: &mut Buffer) {
+        let layout = Layout::horizontal([Constraint::Min(0), Constraint::Length(43)]);
+        let [title, tabs] = layout.areas(area);
+
+        Span::styled("Ratatui", THEME.app_title).render(title, buf);
+        let titles = Tab::iter().map(Tab::title);
+        Tabs::new(titles)
+            .style(THEME.tabs)
+            .highlight_style(THEME.tabs_selected)
+            .select(self.tab as usize)
+            .divider("")
+            .padding("", "")
+            .render(tabs, buf);
+    }
+
+    fn render_selected_tab(&self, area: Rect, buf: &mut Buffer) {
+        match self.tab {
+            Tab::About => self.about_tab.render(area, buf),
+            Tab::Recipe => self.recipe_tab.render(area, buf),
+            Tab::Email => self.email_tab.render(area, buf),
+            Tab::Traceroute => self.traceroute_tab.render(area, buf),
+            Tab::Weather => self.weather_tab.render(area, buf),
+        };
+    }
+
+    fn render_bottom_bar(area: Rect, buf: &mut Buffer) {
+        let keys = [
+            ("H/←", "Left"),
+            ("L/→", "Right"),
+            ("K/↑", "Up"),
+            ("J/↓", "Down"),
+            ("D/Del", "Destroy"),
+            ("Q/Esc", "Quit"),
+        ];
+        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();
+        Line::from(spans)
+            .centered()
+            .style((Color::Indexed(236), Color::Indexed(232)))
+            .render(area, buf);
+    }
+}
+
+impl Tab {
+    fn next(self) -> Self {
+        let current_index = self as usize;
+        let next_index = current_index.saturating_add(1);
+        Self::from_repr(next_index).unwrap_or(self)
+    }
+
+    fn prev(self) -> Self {
+        let current_index = self as usize;
+        let prev_index = current_index.saturating_sub(1);
+        Self::from_repr(prev_index).unwrap_or(self)
+    }
+
+    fn title(self) -> String {
+        match self {
+            Self::About => String::new(),
+            tab => format!(" {tab} "),
+        }
+    }
+}
--- a/examples/demo2/colors.rs
+++ b/examples/demo2/colors.rs
@@ -0,0 +1,35 @@
+use palette::{IntoColor, Okhsv, Srgb};
+use ratatui::{buffer::Buffer, layout::Rect, style::Color, widgets::Widget};
+
+/// 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 {
+    #[allow(clippy::cast_precision_loss, clippy::similar_names)]
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        for (yi, y) in (area.top()..area.bottom()).enumerate() {
+            let value = f32::from(area.height) - yi as f32;
+            let value_fg = value / f32::from(area.height);
+            let value_bg = (value - 0.5) / f32::from(area.height);
+            for (xi, x) in (area.left()..area.right()).enumerate() {
+                let hue = xi as f32 * 360.0 / f32::from(area.width);
+                let fg = color_from_oklab(hue, Okhsv::max_saturation(), value_fg);
+                let bg = color_from_oklab(hue, Okhsv::max_saturation(), value_bg);
+                buf[(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/destroy.rs
+++ b/examples/demo2/destroy.rs
@@ -0,0 +1,142 @@
+use rand::Rng;
+use rand_chacha::rand_core::SeedableRng;
+use ratatui::{
+    buffer::Buffer,
+    layout::{Flex, Layout, Rect},
+    style::{Color, Style},
+    text::Text,
+    widgets::Widget,
+    Frame,
+};
+
+/// delay the start of the animation so it doesn't start immediately
+const DELAY: usize = 120;
+/// higher means more pixels per frame are modified in the animation
+const DRIP_SPEED: usize = 500;
+/// delay the start of the text animation so it doesn't start immediately after the initial delay
+const TEXT_DELAY: usize = 180;
+
+/// Destroy mode activated by pressing `d`
+pub fn destroy(frame: &mut Frame<'_>) {
+    let frame_count = frame.count().saturating_sub(DELAY);
+    if frame_count == 0 {
+        return;
+    }
+
+    let area = frame.area();
+    let buf = frame.buffer_mut();
+
+    drip(frame_count, area, buf);
+    text(frame_count, area, buf);
+}
+
+/// Move a bunch of random pixels down one row.
+///
+/// Each pick some random pixels and move them each down one row. This is a very inefficient way to
+/// do this, but it works well enough for this demo.
+#[allow(
+    clippy::cast_possible_truncation,
+    clippy::cast_precision_loss,
+    clippy::cast_sign_loss
+)]
+fn drip(frame_count: usize, area: Rect, buf: &mut Buffer) {
+    // a seeded rng as we have to move the same random pixels each frame
+    let mut rng = rand_chacha::ChaCha8Rng::seed_from_u64(10);
+    let ramp_frames = 450;
+    let fractional_speed = frame_count as f64 / f64::from(ramp_frames);
+    let variable_speed = DRIP_SPEED as f64 * fractional_speed * fractional_speed * fractional_speed;
+    let pixel_count = (frame_count as f64 * variable_speed).floor() as usize;
+    for _ in 0..pixel_count {
+        let src_x = rng.gen_range(0..area.width);
+        let src_y = rng.gen_range(1..area.height - 2);
+        let src = buf[(src_x, src_y)].clone();
+        // 1% of the time, move a blank or pixel (10:1) to the top line of the screen
+        if rng.gen_ratio(1, 100) {
+            let dest_x = rng
+                .gen_range(src_x.saturating_sub(5)..src_x.saturating_add(5))
+                .clamp(area.left(), area.right() - 1);
+            let dest_y = area.top() + 1;
+
+            let dest = &mut buf[(dest_x, dest_y)];
+            // copy the cell to the new location about 1/10 of the time blank out the cell the rest
+            // of the time. This has the effect of gradually removing the pixels from the screen.
+            if rng.gen_ratio(1, 10) {
+                *dest = src;
+            } else {
+                dest.reset();
+            }
+        } else {
+            // move the pixel down one row
+            let dest_x = src_x;
+            let dest_y = src_y.saturating_add(1).min(area.bottom() - 2);
+            // copy the cell to the new location
+            buf[(dest_x, dest_y)] = src;
+        }
+    }
+}
+
+/// draw some text fading in and out from black to red and back
+#[allow(clippy::cast_possible_truncation, clippy::cast_precision_loss)]
+fn text(frame_count: usize, area: Rect, buf: &mut Buffer) {
+    let sub_frame = frame_count.saturating_sub(TEXT_DELAY);
+    if sub_frame == 0 {
+        return;
+    }
+
+    let logo = indoc::indoc! {"
+        ██████      ████    ██████    ████    ██████  ██    ██  ██
+        ██    ██  ██    ██    ██    ██    ██    ██    ██    ██  ██
+        ██████    ████████    ██    ████████    ██    ██    ██  ██
+        ██  ██    ██    ██    ██    ██    ██    ██    ██    ██  ██
+        ██    ██  ██    ██    ██    ██    ██    ██      ████    ██
+    "};
+    let logo_text = Text::styled(logo, Color::Rgb(255, 255, 255));
+    let area = centered_rect(area, logo_text.width() as u16, logo_text.height() as u16);
+
+    let mask_buf = &mut Buffer::empty(area);
+    logo_text.render(area, mask_buf);
+
+    let percentage = (sub_frame as f64 / 480.0).clamp(0.0, 1.0);
+
+    for row in area.rows() {
+        for col in row.columns() {
+            let cell = &mut buf[(col.x, col.y)];
+            let mask_cell = &mut mask_buf[(col.x, col.y)];
+            cell.set_symbol(mask_cell.symbol());
+
+            // blend the mask cell color with the cell color
+            let cell_color = cell.style().bg.unwrap_or(Color::Rgb(0, 0, 0));
+            let mask_color = mask_cell.style().fg.unwrap_or(Color::Rgb(255, 0, 0));
+
+            let color = blend(mask_color, cell_color, percentage);
+            cell.set_style(Style::new().fg(color));
+        }
+    }
+}
+
+fn blend(mask_color: Color, cell_color: Color, percentage: f64) -> Color {
+    let Color::Rgb(mask_red, mask_green, mask_blue) = mask_color else {
+        return mask_color;
+    };
+    let Color::Rgb(cell_red, cell_green, cell_blue) = cell_color else {
+        return mask_color;
+    };
+
+    let remain = 1.0 - percentage;
+
+    let red = f64::from(mask_red).mul_add(percentage, f64::from(cell_red) * remain);
+    let green = f64::from(mask_green).mul_add(percentage, f64::from(cell_green) * remain);
+    let blue = f64::from(mask_blue).mul_add(percentage, f64::from(cell_blue) * remain);
+
+    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
+    Color::Rgb(red as u8, green as u8, blue as u8)
+}
+
+/// a centered rect of the given size
+fn centered_rect(area: Rect, width: u16, height: u16) -> Rect {
+    let horizontal = Layout::horizontal([width]).flex(Flex::Center);
+    let vertical = Layout::vertical([height]).flex(Flex::Center);
+    let [area] = vertical.areas(area);
+    let [area] = horizontal.areas(area);
+    area
+}
--- a/examples/demo2/main.rs
+++ b/examples/demo2/main.rs
@@ -0,0 +1,54 @@
+//! # [Ratatui] Demo2 example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+#![allow(
+    clippy::missing_errors_doc,
+    clippy::module_name_repetitions,
+    clippy::must_use_candidate
+)]
+
+mod app;
+mod colors;
+mod destroy;
+mod tabs;
+mod theme;
+
+use std::io::stdout;
+
+use app::App;
+use color_eyre::Result;
+use crossterm::{
+    execute,
+    terminal::{EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{layout::Rect, TerminalOptions, Viewport};
+
+pub use self::{
+    colors::{color_from_oklab, RgbSwatch},
+    theme::THEME,
+};
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    // 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 viewport = Viewport::Fixed(Rect::new(0, 0, 81, 18));
+    let terminal = ratatui::init_with_options(TerminalOptions { viewport });
+    execute!(stdout(), EnterAlternateScreen).expect("failed to enter alternate screen");
+    let app_result = App::default().run(terminal);
+    execute!(stdout(), LeaveAlternateScreen).expect("failed to leave alternate screen");
+    ratatui::restore();
+    app_result
+}
--- 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,165 @@
+use itertools::Itertools;
+use ratatui::{
+    buffer::Buffer,
+    layout::{Alignment, Constraint, Layout, Margin, Rect},
+    widgets::{Block, Borders, Clear, Padding, Paragraph, Widget, Wrap},
+};
+
+use crate::{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█ █     ",
+];
+
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct AboutTab {
+    row_index: usize,
+}
+
+impl AboutTab {
+    pub fn prev_row(&mut self) {
+        self.row_index = self.row_index.saturating_sub(1);
+    }
+
+    pub fn next_row(&mut self) {
+        self.row_index = self.row_index.saturating_add(1);
+    }
+}
+
+impl Widget for AboutTab {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        RgbSwatch.render(area, buf);
+        let horizontal = Layout::horizontal([Constraint::Length(34), Constraint::Min(0)]);
+        let [description, logo] = horizontal.areas(area);
+        render_crate_description(description, buf);
+        render_logo(self.row_index, logo, 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.
+#[allow(clippy::cast_possible_truncation)]
+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 = &mut buf[(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.bg = 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,161 @@
+use itertools::Itertools;
+use ratatui::{
+    buffer::Buffer,
+    layout::{Constraint, Layout, Margin, Rect},
+    style::{Styled, Stylize},
+    text::Line,
+    widgets::{
+        Block, BorderType, Borders, Clear, List, ListItem, ListState, Padding, Paragraph,
+        Scrollbar, ScrollbarState, StatefulWidget, Tabs, Widget,
+    },
+};
+use unicode_width::UnicodeWidthStr;
+
+use crate::{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, Clone, Copy, Default, PartialEq, Eq)]
+pub struct EmailTab {
+    row_index: usize,
+}
+
+impl EmailTab {
+    /// Select the previous email (with wrap around).
+    pub fn prev(&mut self) {
+        self.row_index = self.row_index.saturating_add(EMAILS.len() - 1) % EMAILS.len();
+    }
+
+    /// Select the next email (with wrap around).
+    pub fn next(&mut self) {
+        self.row_index = self.row_index.saturating_add(1) % 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 vertical = Layout::vertical([Constraint::Length(5), Constraint::Min(0)]);
+        let [inbox, email] = vertical.areas(area);
+        render_inbox(self.row_index, inbox, buf);
+        render_email(self.row_index, email, buf);
+    }
+}
+fn render_inbox(selected_index: usize, area: Rect, buf: &mut Buffer) {
+    let vertical = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
+    let [tabs, inbox] = vertical.areas(area);
+    let theme = THEME.email;
+    Tabs::new(vec![" Inbox ", " Sent ", " Drafts "])
+        .style(theme.tabs)
+        .highlight_style(theme.tabs_selected)
+        .select(0)
+        .divider("")
+        .render(tabs, 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),
+        inbox,
+        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(inbox, 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 vertical = Layout::vertical([Constraint::Length(3), Constraint::Min(0)]);
+        let [headers_area, body_area] = vertical.areas(inner);
+        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(headers_area, buf);
+        let body = email.body.lines().map(Line::from).collect_vec();
+        Paragraph::new(body)
+            .style(theme.body)
+            .render(body_area, 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,185 @@
+use itertools::Itertools;
+use ratatui::{
+    buffer::Buffer,
+    layout::{Alignment, Constraint, Layout, Margin, Rect},
+    style::{Style, Stylize},
+    text::Line,
+    widgets::{
+        Block, Clear, Padding, Paragraph, Row, Scrollbar, ScrollbarOrientation, ScrollbarState,
+        StatefulWidget, Table, TableState, Widget, Wrap,
+    },
+};
+
+use crate::{RgbSwatch, THEME};
+
+#[derive(Debug, Default, Clone, Copy)]
+struct Ingredient {
+    quantity: &'static str,
+    name: &'static str,
+}
+
+impl Ingredient {
+    #[allow(clippy::cast_possible_truncation)]
+    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, Default, Clone, Copy, PartialEq, Eq)]
+pub struct RecipeTab {
+    row_index: usize,
+}
+
+impl RecipeTab {
+    /// Select the previous item in the ingredients list (with wrap around)
+    pub fn prev(&mut self) {
+        self.row_index = self.row_index.saturating_add(INGREDIENTS.len() - 1) % INGREDIENTS.len();
+    }
+
+    /// Select the next item in the ingredients list (with wrap around)
+    pub fn next(&mut self) {
+        self.row_index = self.row_index.saturating_add(1) % 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.row_index, scrollbar_area, buf);
+
+        let area = area.inner(Margin {
+            horizontal: 2,
+            vertical: 1,
+        });
+        let [recipe, ingredients] =
+            Layout::horizontal([Constraint::Length(44), Constraint::Min(0)]).areas(area);
+
+        render_recipe(recipe, buf);
+        render_ingredients(self.row_index, ingredients, 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().copied();
+    let theme = THEME.recipe;
+    StatefulWidget::render(
+        Table::new(rows, [Constraint::Length(7), Constraint::Length(30)])
+            .block(Block::new().style(theme.ingredients))
+            .header(Row::new(vec!["Qty", "Ingredient"]).style(theme.ingredients_header))
+            .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,209 @@
+use itertools::Itertools;
+use ratatui::{
+    buffer::Buffer,
+    layout::{Alignment, Constraint, Layout, Margin, Rect},
+    style::{Styled, Stylize},
+    symbols::Marker,
+    widgets::{
+        canvas::{self, Canvas, Map, MapResolution, Points},
+        Block, BorderType, Clear, Padding, Row, Scrollbar, ScrollbarOrientation, ScrollbarState,
+        Sparkline, StatefulWidget, Table, TableState, Widget,
+    },
+};
+
+use crate::{RgbSwatch, THEME};
+
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct TracerouteTab {
+    row_index: usize,
+}
+
+impl TracerouteTab {
+    /// Select the previous row (with wrap around).
+    pub fn prev_row(&mut self) {
+        self.row_index = self.row_index.saturating_add(HOPS.len() - 1) % HOPS.len();
+    }
+
+    /// Select the next row (with wrap around).
+    pub fn next_row(&mut self) {
+        self.row_index = self.row_index.saturating_add(1) % 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 horizontal = Layout::horizontal([Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)]);
+        let vertical = Layout::vertical([Constraint::Min(0), Constraint::Length(3)]);
+        let [left, map] = horizontal.areas(area);
+        let [hops, pings] = vertical.areas(left);
+
+        render_hops(self.row_index, hops, buf);
+        render_ping(self.row_index, pings, buf);
+        render_map(self.row_index, map, 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::new()
+        .padding(Padding::new(1, 1, 1, 1))
+        .title_alignment(Alignment::Center)
+        .title("Traceroute bad.horse".bold().white());
+    StatefulWidget::render(
+        Table::new(rows, [Constraint::Max(100), Constraint::Length(15)])
+            .header(Row::new(vec!["Host", "Address"]).set_style(THEME.traceroute.header))
+            .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: 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,164 @@
+use itertools::Itertools;
+use palette::Okhsv;
+use ratatui::{
+    buffer::Buffer,
+    layout::{Constraint, Direction, Layout, Margin, Rect},
+    style::{Color, Style, Stylize},
+    symbols,
+    widgets::{
+        calendar::{CalendarEventStore, Monthly},
+        Bar, BarChart, BarGroup, Block, Clear, LineGauge, Padding, Widget,
+    },
+};
+use time::OffsetDateTime;
+
+use crate::{color_from_oklab, RgbSwatch, THEME};
+
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct WeatherTab {
+    pub download_progress: usize,
+}
+
+impl WeatherTab {
+    /// Simulate a download indicator by decrementing the row index.
+    pub fn prev(&mut self) {
+        self.download_progress = self.download_progress.saturating_sub(1);
+    }
+
+    /// Simulate a download indicator by incrementing the row index.
+    pub fn next(&mut self) {
+        self.download_progress = self.download_progress.saturating_add(1);
+    }
+}
+
+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 [main, _, gauges] = Layout::vertical([
+            Constraint::Min(0),
+            Constraint::Length(1),
+            Constraint::Length(1),
+        ])
+        .areas(area);
+        let [calendar, charts] =
+            Layout::horizontal([Constraint::Length(23), Constraint::Min(0)]).areas(main);
+        let [simple, horizontal] =
+            Layout::vertical([Constraint::Length(29), Constraint::Min(0)]).areas(charts);
+
+        render_calendar(calendar, buf);
+        render_simple_barchart(simple, buf);
+        render_horizontal_barchart(horizontal, buf);
+        render_gauge(self.download_progress, gauges, buf);
+    }
+}
+
+fn render_calendar(area: Rect, buf: &mut Buffer) {
+    let date = OffsetDateTime::now_utc().date();
+    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/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);
+}
+
+#[allow(clippy::cast_precision_loss)]
+pub fn render_gauge(progress: usize, area: Rect, buf: &mut Buffer) {
+    let percent = (progress * 3).min(100) as f64;
+
+    render_line_gauge(percent, area, buf);
+}
+
+#[allow(clippy::cast_possible_truncation)]
+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 filled_color = color_from_oklab(hue, Okhsv::max_saturation(), value);
+    let unfilled_color = 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())
+        .filled_style(Style::new().fg(filled_color))
+        .unfilled_style(Style::new().fg(unfilled_color))
+        .line_set(symbols::line::THICK)
+        .render(area, buf);
+}
--- a/examples/demo2/theme.rs
+++ b/examples/demo2/theme.rs
@@ -0,0 +1,136 @@
+use ratatui::style::{Color, Modifier, Style};
+
+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::Rgb(215, 0, 0);
+const BLACK: Color = Color::Rgb(8, 8, 8); // not really black, often #080808
+const DARK_GRAY: Color = Color::Rgb(68, 68, 68);
+const MID_GRAY: Color = Color::Rgb(128, 128, 128);
+const LIGHT_GRAY: Color = Color::Rgb(188, 188, 188);
+const WHITE: Color = Color::Rgb(238, 238, 238); // not really white, often #eeeeee
--- a/examples/docsrs.rs
+++ b/examples/docsrs.rs
@@ -0,0 +1,127 @@
+//! # [Ratatui] Docs.rs example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+use color_eyre::Result;
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode},
+    layout::{Constraint, Layout},
+    style::{Color, Modifier, Style, Stylize},
+    text::{Line, Span, Text},
+    widgets::{Block, Borders, Paragraph},
+    DefaultTerminal, Frame,
+};
+
+/// Example code for lib.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() -> Result<()> {
+    color_eyre::install()?;
+    let first_arg = std::env::args().nth(1).unwrap_or_default();
+    let terminal = ratatui::init();
+    let app_result = run(terminal, &first_arg);
+    ratatui::restore();
+    app_result
+}
+
+fn run(mut terminal: DefaultTerminal, first_arg: &str) -> Result<()> {
+    let mut should_quit = false;
+    while !should_quit {
+        terminal.draw(match first_arg {
+            "layout" => layout,
+            "styling" => styling,
+            _ => hello_world,
+        })?;
+        should_quit = handle_events()?;
+    }
+    Ok(())
+}
+
+fn handle_events() -> std::io::Result<bool> {
+    if let Event::Key(key) = event::read()? {
+        if key.kind == event::KeyEventKind::Press && key.code == KeyCode::Char('q') {
+            return Ok(true);
+        }
+    }
+    Ok(false)
+}
+
+fn hello_world(frame: &mut Frame) {
+    frame.render_widget(
+        Paragraph::new("Hello World!").block(Block::bordered().title("Greeting")),
+        frame.area(),
+    );
+}
+
+fn layout(frame: &mut Frame) {
+    let vertical = Layout::vertical([
+        Constraint::Length(1),
+        Constraint::Min(0),
+        Constraint::Length(1),
+    ]);
+    let horizontal = Layout::horizontal([Constraint::Ratio(1, 2); 2]);
+    let [title_bar, main_area, status_bar] = vertical.areas(frame.area());
+    let [left, right] = horizontal.areas(main_area);
+
+    frame.render_widget(
+        Block::new().borders(Borders::TOP).title("Title Bar"),
+        title_bar,
+    );
+    frame.render_widget(
+        Block::new().borders(Borders::TOP).title("Status Bar"),
+        status_bar,
+    );
+    frame.render_widget(Block::bordered().title("Left"), left);
+    frame.render_widget(Block::bordered().title("Right"), right);
+}
+
+fn styling(frame: &mut Frame) {
+    let areas = Layout::vertical([
+        Constraint::Length(1),
+        Constraint::Length(1),
+        Constraint::Length(1),
+        Constraint::Length(1),
+        Constraint::Min(0),
+    ])
+    .split(frame.area());
+
+    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/flex.rs
+++ b/examples/flex.rs
@@ -0,0 +1,530 @@
+//! # [Ratatui] Flex example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+use std::num::NonZeroUsize;
+
+use color_eyre::Result;
+use ratatui::{
+    buffer::Buffer,
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{
+        Alignment,
+        Constraint::{self, Fill, Length, Max, Min, Percentage, Ratio},
+        Flex, Layout, Rect,
+    },
+    style::{palette::tailwind, Color, Modifier, Style, Stylize},
+    symbols::{self, line},
+    text::{Line, Text},
+    widgets::{
+        block::Title, Block, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState,
+        StatefulWidget, Tabs, Widget,
+    },
+    DefaultTerminal,
+};
+use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
+const EXAMPLE_DATA: &[(&str, &[Constraint])] = &[
+    (
+        "Min(u16) takes any excess space always",
+        &[Length(10), Min(10), Max(10), Percentage(10), Ratio(1,10)],
+    ),
+    (
+        "Fill(u16) takes any excess space always",
+        &[Length(20), Percentage(20), Ratio(1, 5), Fill(1)],
+    ),
+    (
+        "Here's all constraints in one line",
+        &[Length(10), Min(10), Max(10), Percentage(10), Ratio(1,10), Fill(1)],
+    ),
+    (
+        "",
+        &[Max(50), Min(50)],
+    ),
+    (
+        "",
+        &[Max(20), Length(10)],
+    ),
+    (
+        "",
+        &[Max(20), Length(10)],
+    ),
+    (
+        "Min grows always but also allows Fill to grow",
+        &[Percentage(50), Fill(1), Fill(2), Min(50)],
+    ),
+    (
+        "In `Legacy`, the last constraint of lowest priority takes excess space",
+        &[Length(20), Length(20), Percentage(20)],
+    ),
+    ("", &[Length(20), Percentage(20), Length(20)]),
+    ("A lowest priority constraint will be broken before a high priority constraint", &[Ratio(1,4), Percentage(20)]),
+    ("`Length` is higher priority than `Percentage`", &[Percentage(20), Length(10)]),
+    ("`Min/Max` is higher priority than `Length`", &[Length(10), Max(20)]),
+    ("", &[Length(100), Min(20)]),
+    ("`Length` is higher priority than `Min/Max`", &[Max(20), Length(10)]),
+    ("", &[Min(20), Length(90)]),
+    ("Fill is the lowest priority and will fill any excess space", &[Fill(1), Ratio(1, 4)]),
+    ("Fill can be used to scale proportionally with other Fill blocks", &[Fill(1), Percentage(20), Fill(2)]),
+    ("", &[Ratio(1, 3), Percentage(20), Ratio(2, 3)]),
+    ("Legacy will stretch the last lowest priority constraint\nStretch will only stretch equal weighted constraints", &[Length(20), Length(15)]),
+    ("", &[Percentage(20), Length(15)]),
+    ("`Fill(u16)` fills up excess space, but is lower priority to spacers.\ni.e. Fill will only have widths in Flex::Stretch and Flex::Legacy", &[Fill(1), Fill(1)]),
+    ("", &[Length(20), Length(20)]),
+    (
+        "When not using `Flex::Stretch` or `Flex::Legacy`,\n`Min(u16)` and `Max(u16)` collapse to their lowest values",
+        &[Min(20), Max(20)],
+    ),
+    (
+        "",
+        &[Max(20)],
+    ),
+    ("", &[Min(20), Max(20), Length(20), Length(20)]),
+    ("", &[Fill(0), Fill(0)]),
+    (
+        "`Fill(1)` can be to scale with respect to other `Fill(2)`",
+        &[Fill(1), Fill(2)],
+    ),
+    (
+        "",
+        &[Fill(1), Min(10), Max(10), Fill(2)],
+    ),
+    (
+        "`Fill(0)` collapses if there are other non-zero `Fill(_)`\nconstraints. e.g. `[Fill(0), Fill(0), Fill(1)]`:",
+        &[
+            Fill(0),
+            Fill(0),
+            Fill(1),
+        ],
+    ),
+];
+
+#[derive(Default, Clone, Copy)]
+struct App {
+    selected_tab: SelectedTab,
+    scroll_offset: u16,
+    spacing: u16,
+    state: AppState,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+enum AppState {
+    #[default]
+    Running,
+    Quit,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct Example {
+    constraints: Vec<Constraint>,
+    description: String,
+    flex: Flex,
+    spacing: u16,
+}
+
+/// Tabs for the different layouts
+///
+/// Note: the order of the variants will determine the order of the tabs this uses several derive
+/// macros from the `strum` crate to make it easier to iterate over the variants.
+/// (`FromRepr`,`Display`,`EnumIter`).
+#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, FromRepr, Display, EnumIter)]
+enum SelectedTab {
+    #[default]
+    Legacy,
+    Start,
+    Center,
+    End,
+    SpaceAround,
+    SpaceBetween,
+}
+
+impl App {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        // increase the layout cache to account for the number of layout events. This ensures that
+        // layout is not generally reprocessed on every frame (which would lead to possible janky
+        // results when there are more than one possible solution to the requested layout). This
+        // assumes the user changes spacing about a 100 times or so.
+        let cache_size = EXAMPLE_DATA.len() * SelectedTab::iter().len() * 100;
+        Layout::init_cache(NonZeroUsize::new(cache_size).unwrap());
+
+        while self.is_running() {
+            terminal.draw(|frame| frame.render_widget(self, frame.area()))?;
+            self.handle_events()?;
+        }
+        Ok(())
+    }
+
+    fn is_running(self) -> bool {
+        self.state == AppState::Running
+    }
+
+    fn handle_events(&mut self) -> Result<()> {
+        match event::read()? {
+            Event::Key(key) if key.kind == KeyEventKind::Press => match key.code {
+                KeyCode::Char('q') | KeyCode::Esc => self.quit(),
+                KeyCode::Char('l') | KeyCode::Right => self.next(),
+                KeyCode::Char('h') | KeyCode::Left => self.previous(),
+                KeyCode::Char('j') | KeyCode::Down => self.down(),
+                KeyCode::Char('k') | KeyCode::Up => self.up(),
+                KeyCode::Char('g') | KeyCode::Home => self.top(),
+                KeyCode::Char('G') | KeyCode::End => self.bottom(),
+                KeyCode::Char('+') => self.increment_spacing(),
+                KeyCode::Char('-') => self.decrement_spacing(),
+                _ => (),
+            },
+            _ => {}
+        }
+        Ok(())
+    }
+
+    fn next(&mut self) {
+        self.selected_tab = self.selected_tab.next();
+    }
+
+    fn previous(&mut self) {
+        self.selected_tab = self.selected_tab.previous();
+    }
+
+    fn up(&mut self) {
+        self.scroll_offset = self.scroll_offset.saturating_sub(1);
+    }
+
+    fn down(&mut self) {
+        self.scroll_offset = self
+            .scroll_offset
+            .saturating_add(1)
+            .min(max_scroll_offset());
+    }
+
+    fn top(&mut self) {
+        self.scroll_offset = 0;
+    }
+
+    fn bottom(&mut self) {
+        self.scroll_offset = max_scroll_offset();
+    }
+
+    fn increment_spacing(&mut self) {
+        self.spacing = self.spacing.saturating_add(1);
+    }
+
+    fn decrement_spacing(&mut self) {
+        self.spacing = self.spacing.saturating_sub(1);
+    }
+
+    fn quit(&mut self) {
+        self.state = AppState::Quit;
+    }
+}
+
+// when scrolling, make sure we don't scroll past the last example
+fn max_scroll_offset() -> u16 {
+    example_height()
+        - EXAMPLE_DATA
+            .last()
+            .map_or(0, |(desc, _)| get_description_height(desc) + 4)
+}
+
+/// The height of all examples combined
+///
+/// Each may or may not have a title so we need to account for that.
+fn example_height() -> u16 {
+    EXAMPLE_DATA
+        .iter()
+        .map(|(desc, _)| get_description_height(desc) + 4)
+        .sum()
+}
+
+impl Widget for App {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let layout = Layout::vertical([Length(3), Length(1), Fill(0)]);
+        let [tabs, axis, demo] = layout.areas(area);
+        self.tabs().render(tabs, buf);
+        let scroll_needed = self.render_demo(demo, buf);
+        let axis_width = if scroll_needed {
+            axis.width.saturating_sub(1)
+        } else {
+            axis.width
+        };
+        Self::axis(axis_width, self.spacing).render(axis, buf);
+    }
+}
+
+impl App {
+    fn tabs(self) -> impl Widget {
+        let tab_titles = SelectedTab::iter().map(SelectedTab::to_tab_title);
+        let block = Block::new()
+            .title(Title::from("Flex Layouts ".bold()))
+            .title(" Use ◄ ► to change tab, ▲ ▼  to scroll, - + to change spacing ");
+        Tabs::new(tab_titles)
+            .block(block)
+            .highlight_style(Modifier::REVERSED)
+            .select(self.selected_tab as usize)
+            .divider(" ")
+            .padding("", "")
+    }
+
+    /// a bar like `<----- 80 px (gap: 2 px)? ----->`
+    fn axis(width: u16, spacing: u16) -> impl Widget {
+        let width = width as usize;
+        // only show gap when spacing is not zero
+        let label = if spacing != 0 {
+            format!("{width} px (gap: {spacing} px)")
+        } else {
+            format!("{width} px")
+        };
+        let bar_width = width.saturating_sub(2); // we want to `<` and `>` at the ends
+        let width_bar = format!("<{label:-^bar_width$}>");
+        Paragraph::new(width_bar.dark_gray()).centered()
+    }
+
+    /// Render the demo content
+    ///
+    /// This function renders the demo content into a separate buffer and then splices the buffer
+    /// into the main buffer. This is done to make it possible to handle scrolling easily.
+    ///
+    /// Returns bool indicating whether scroll was needed
+    #[allow(clippy::cast_possible_truncation)]
+    fn render_demo(self, area: Rect, buf: &mut Buffer) -> bool {
+        // render demo content into a separate buffer so all examples fit we add an extra
+        // area.height to make sure the last example is fully visible even when the scroll offset is
+        // at the max
+        let height = example_height();
+        let demo_area = Rect::new(0, 0, area.width, height);
+        let mut demo_buf = Buffer::empty(demo_area);
+
+        let scrollbar_needed = self.scroll_offset != 0 || height > area.height;
+        let content_area = if scrollbar_needed {
+            Rect {
+                width: demo_area.width - 1,
+                ..demo_area
+            }
+        } else {
+            demo_area
+        };
+
+        let mut spacing = self.spacing;
+        self.selected_tab
+            .render(content_area, &mut demo_buf, &mut spacing);
+
+        let visible_content = demo_buf
+            .content
+            .into_iter()
+            .skip((area.width * self.scroll_offset) as usize)
+            .take(area.area() as usize);
+        for (i, cell) in visible_content.enumerate() {
+            let x = i as u16 % area.width;
+            let y = i as u16 / area.width;
+            buf[(area.x + x, area.y + y)] = cell;
+        }
+
+        if scrollbar_needed {
+            let area = area.intersection(buf.area);
+            let mut state = ScrollbarState::new(max_scroll_offset() as usize)
+                .position(self.scroll_offset as usize);
+            Scrollbar::new(ScrollbarOrientation::VerticalRight).render(area, buf, &mut state);
+        }
+        scrollbar_needed
+    }
+}
+
+impl SelectedTab {
+    /// Get the previous tab, if there is no previous tab return the current tab.
+    fn previous(self) -> Self {
+        let current_index: usize = self as usize;
+        let previous_index = current_index.saturating_sub(1);
+        Self::from_repr(previous_index).unwrap_or(self)
+    }
+
+    /// Get the next tab, if there is no next tab return the current tab.
+    fn next(self) -> Self {
+        let current_index = self as usize;
+        let next_index = current_index.saturating_add(1);
+        Self::from_repr(next_index).unwrap_or(self)
+    }
+
+    /// Convert a `SelectedTab` into a `Line` to display it by the `Tabs` widget.
+    fn to_tab_title(value: Self) -> Line<'static> {
+        use tailwind::{INDIGO, ORANGE, SKY};
+        let text = value.to_string();
+        let color = match value {
+            Self::Legacy => ORANGE.c400,
+            Self::Start => SKY.c400,
+            Self::Center => SKY.c300,
+            Self::End => SKY.c200,
+            Self::SpaceAround => INDIGO.c400,
+            Self::SpaceBetween => INDIGO.c300,
+        };
+        format!(" {text} ").fg(color).bg(Color::Black).into()
+    }
+}
+
+impl StatefulWidget for SelectedTab {
+    type State = u16;
+    fn render(self, area: Rect, buf: &mut Buffer, spacing: &mut Self::State) {
+        let spacing = *spacing;
+        match self {
+            Self::Legacy => Self::render_examples(area, buf, Flex::Legacy, spacing),
+            Self::Start => Self::render_examples(area, buf, Flex::Start, spacing),
+            Self::Center => Self::render_examples(area, buf, Flex::Center, spacing),
+            Self::End => Self::render_examples(area, buf, Flex::End, spacing),
+            Self::SpaceAround => Self::render_examples(area, buf, Flex::SpaceAround, spacing),
+            Self::SpaceBetween => Self::render_examples(area, buf, Flex::SpaceBetween, spacing),
+        }
+    }
+}
+
+impl SelectedTab {
+    fn render_examples(area: Rect, buf: &mut Buffer, flex: Flex, spacing: u16) {
+        let heights = EXAMPLE_DATA
+            .iter()
+            .map(|(desc, _)| get_description_height(desc) + 4);
+        let areas = Layout::vertical(heights).flex(Flex::Start).split(area);
+        for (area, (description, constraints)) in areas.iter().zip(EXAMPLE_DATA.iter()) {
+            Example::new(constraints, description, flex, spacing).render(*area, buf);
+        }
+    }
+}
+
+impl Example {
+    fn new(constraints: &[Constraint], description: &str, flex: Flex, spacing: u16) -> Self {
+        Self {
+            constraints: constraints.into(),
+            description: description.into(),
+            flex,
+            spacing,
+        }
+    }
+}
+
+impl Widget for Example {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let title_height = get_description_height(&self.description);
+        let layout = Layout::vertical([Length(title_height), Fill(0)]);
+        let [title, illustrations] = layout.areas(area);
+
+        let (blocks, spacers) = Layout::horizontal(&self.constraints)
+            .flex(self.flex)
+            .spacing(self.spacing)
+            .split_with_spacers(illustrations);
+
+        if !self.description.is_empty() {
+            Paragraph::new(
+                self.description
+                    .split('\n')
+                    .map(|s| format!("// {s}").italic().fg(tailwind::SLATE.c400))
+                    .map(Line::from)
+                    .collect::<Vec<Line>>(),
+            )
+            .render(title, buf);
+        }
+
+        for (block, constraint) in blocks.iter().zip(&self.constraints) {
+            Self::illustration(*constraint, block.width).render(*block, buf);
+        }
+
+        for spacer in spacers.iter() {
+            Self::render_spacer(*spacer, buf);
+        }
+    }
+}
+
+impl Example {
+    fn render_spacer(spacer: Rect, buf: &mut Buffer) {
+        if spacer.width > 1 {
+            let corners_only = symbols::border::Set {
+                top_left: line::NORMAL.top_left,
+                top_right: line::NORMAL.top_right,
+                bottom_left: line::NORMAL.bottom_left,
+                bottom_right: line::NORMAL.bottom_right,
+                vertical_left: " ",
+                vertical_right: " ",
+                horizontal_top: " ",
+                horizontal_bottom: " ",
+            };
+            Block::bordered()
+                .border_set(corners_only)
+                .border_style(Style::reset().dark_gray())
+                .render(spacer, buf);
+        } else {
+            Paragraph::new(Text::from(vec![
+                Line::from(""),
+                Line::from("│"),
+                Line::from("│"),
+                Line::from(""),
+            ]))
+            .style(Style::reset().dark_gray())
+            .render(spacer, buf);
+        }
+        let width = spacer.width;
+        let label = if width > 4 {
+            format!("{width} px")
+        } else if width > 2 {
+            format!("{width}")
+        } else {
+            String::new()
+        };
+        let text = Text::from(vec![
+            Line::raw(""),
+            Line::raw(""),
+            Line::styled(label, Style::reset().dark_gray()),
+        ]);
+        Paragraph::new(text)
+            .style(Style::reset().dark_gray())
+            .alignment(Alignment::Center)
+            .render(spacer, buf);
+    }
+
+    fn illustration(constraint: Constraint, width: u16) -> impl Widget {
+        let main_color = color_for_constraint(constraint);
+        let fg_color = Color::White;
+        let title = format!("{constraint}");
+        let content = format!("{width} px");
+        let text = format!("{title}\n{content}");
+        let block = Block::bordered()
+            .border_set(symbols::border::QUADRANT_OUTSIDE)
+            .border_style(Style::reset().fg(main_color).reversed())
+            .style(Style::default().fg(fg_color).bg(main_color));
+        Paragraph::new(text).centered().block(block)
+    }
+}
+
+const fn color_for_constraint(constraint: Constraint) -> Color {
+    use tailwind::{BLUE, SLATE};
+    match constraint {
+        Constraint::Min(_) => BLUE.c900,
+        Constraint::Max(_) => BLUE.c800,
+        Constraint::Length(_) => SLATE.c700,
+        Constraint::Percentage(_) => SLATE.c800,
+        Constraint::Ratio(_, _) => SLATE.c900,
+        Constraint::Fill(_) => SLATE.c950,
+    }
+}
+
+#[allow(clippy::cast_possible_truncation)]
+fn get_description_height(s: &str) -> u16 {
+    if s.is_empty() {
+        0
+    } else {
+        s.split('\n').count() as u16
+    }
+}
--- a/examples/gauge.rs
+++ b/examples/gauge.rs
@@ -1,150 +1,205 @@
-extern crate tui;
-extern crate termion;
+//! # [Ratatui] Gauge example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md

-use std::io;
-use std::thread;
-use std::time;
-use std::sync::mpsc;
+use std::time::Duration;

-use termion::event;
-use termion::input::TermRead;
+use color_eyre::Result;
+use ratatui::{
+    buffer::Buffer,
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Alignment, Constraint, Layout, Rect},
+    style::{palette::tailwind, Color, Style, Stylize},
+    text::Span,
+    widgets::{block::Title, Block, Borders, Gauge, Padding, Paragraph, Widget},
+    DefaultTerminal,
+};

-use tui::Terminal;
-use tui::backend::TermionBackend;
-use tui::widgets::{Widget, Block, border, Gauge};
-use tui::layout::{Group, Direction, Size};
-use tui::style::{Style, Color, Modifier};
+const GAUGE1_COLOR: Color = tailwind::RED.c800;
+const GAUGE2_COLOR: Color = tailwind::GREEN.c800;
+const GAUGE3_COLOR: Color = tailwind::BLUE.c800;
+const GAUGE4_COLOR: Color = tailwind::ORANGE.c800;
+const CUSTOM_LABEL_COLOR: Color = tailwind::SLATE.c200;

+#[derive(Debug, Default, Clone, Copy)]
 struct App {
+    state: AppState,
+    progress_columns: u16,
    progress1: u16,
-    progress2: u16,
-    progress3: u16,
-    progress4: u16,
+    progress2: f64,
+    progress3: f64,
+    progress4: f64,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+enum AppState {
+    #[default]
+    Running,
+    Started,
+    Quitting,
+}
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
 }

 impl App {
-    fn new() -> App {
-        App {
-            progress1: 0,
-            progress2: 0,
-            progress3: 0,
-            progress4: 0,
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        while self.state != AppState::Quitting {
+            terminal.draw(|frame| frame.render_widget(&self, frame.area()))?;
+            self.handle_events()?;
+            self.update(terminal.size()?.width);
        }
+        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;
+    fn update(&mut self, terminal_width: u16) {
+        if self.state != AppState::Started {
+            return;
        }
+
+        // progress1 and progress2 help show the difference between ratio and percentage measuring
+        // the same thing, but converting to either a u16 or f64. Effectively, we're showing the
+        // difference between how a continuous gauge acts for floor and rounded values.
+        self.progress_columns = (self.progress_columns + 1).clamp(0, terminal_width);
+        self.progress1 = self.progress_columns * 100 / terminal_width;
+        self.progress2 = f64::from(self.progress_columns) * 100.0 / f64::from(terminal_width);
+
+        // progress3 and progress4 similarly show the difference between unicode and non-unicode
+        // gauges measuring the same thing.
+        self.progress3 = (self.progress3 + 0.1).clamp(40.0, 100.0);
+        self.progress4 = (self.progress4 + 0.1).clamp(40.0, 100.0);
    }
-}

-enum Event {
-    Input(event::Key),
-    Tick,
-}
-
-fn main() {
-    // Terminal initialization
-    let backend = TermionBackend::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();
-    draw(&mut terminal, &app);
-
-    loop {
-        let evt = rx.recv().unwrap();
-        match evt {
-            Event::Input(input) => {
-                if input == event::Key::Char('q') {
-                    break;
+    fn handle_events(&mut self) -> Result<()> {
+        let timeout = Duration::from_secs_f32(1.0 / 20.0);
+        if event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                if key.kind == KeyEventKind::Press {
+                    match key.code {
+                        KeyCode::Char(' ') | KeyCode::Enter => self.start(),
+                        KeyCode::Char('q') | KeyCode::Esc => self.quit(),
+                        _ => {}
+                    }
                }
            }
-            Event::Tick => {
-                app.advance();
-            }
        }
-        draw(&mut terminal, &app);
+        Ok(())
    }

-    terminal.show_cursor().unwrap();
+    fn start(&mut self) {
+        self.state = AppState::Started;
+    }
+
+    fn quit(&mut self) {
+        self.state = AppState::Quitting;
+    }
 }

-fn draw(t: &mut Terminal<TermionBackend>, app: &App) {
+impl Widget for &App {
+    #[allow(clippy::similar_names)]
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        use Constraint::{Length, Min, Ratio};
+        let layout = Layout::vertical([Length(2), Min(0), Length(1)]);
+        let [header_area, gauge_area, footer_area] = layout.areas(area);

-    let size = t.size().unwrap();
+        let layout = Layout::vertical([Ratio(1, 4); 4]);
+        let [gauge1_area, gauge2_area, gauge3_area, gauge4_area] = layout.areas(gauge_area);

-    Group::default()
-        .direction(Direction::Vertical)
-        .margin(2)
-        .sizes(&[Size::Percent(25), Size::Percent(25), Size::Percent(25), Size::Percent(25)])
-        .render(t, &size, |t, chunks| {
-            Gauge::default()
-                .block(Block::default().title("Gauge1").borders(border::ALL))
-                .style(Style::default().fg(Color::Yellow))
-                .percent(app.progress1)
-                .render(t, &chunks[0]);
-            Gauge::default()
-                .block(Block::default().title("Gauge2").borders(border::ALL))
-                .style(Style::default().fg(Color::Magenta).bg(Color::Green))
-                .percent(app.progress2)
-                .label(&format!("{}/100", app.progress2))
-                .render(t, &chunks[1]);
-            Gauge::default()
-                .block(Block::default().title("Gauge2").borders(border::ALL))
-                .style(Style::default().fg(Color::Yellow))
-                .percent(app.progress3)
-                .render(t, &chunks[2]);
-            Gauge::default()
-                .block(Block::default().title("Gauge3").borders(border::ALL))
-                .style(Style::default().fg(Color::Cyan).modifier(Modifier::Italic))
-                .percent(app.progress4)
-                .label(&format!("{}/100", app.progress2))
-                .render(t, &chunks[3]);
-        });
+        render_header(header_area, buf);
+        render_footer(footer_area, buf);

-    t.draw().unwrap();
+        self.render_gauge1(gauge1_area, buf);
+        self.render_gauge2(gauge2_area, buf);
+        self.render_gauge3(gauge3_area, buf);
+        self.render_gauge4(gauge4_area, buf);
+    }
+}
+
+fn render_header(area: Rect, buf: &mut Buffer) {
+    Paragraph::new("Ratatui Gauge Example")
+        .bold()
+        .alignment(Alignment::Center)
+        .fg(CUSTOM_LABEL_COLOR)
+        .render(area, buf);
+}
+
+fn render_footer(area: Rect, buf: &mut Buffer) {
+    Paragraph::new("Press ENTER to start")
+        .alignment(Alignment::Center)
+        .fg(CUSTOM_LABEL_COLOR)
+        .bold()
+        .render(area, buf);
+}
+
+impl App {
+    fn render_gauge1(&self, area: Rect, buf: &mut Buffer) {
+        let title = title_block("Gauge with percentage");
+        Gauge::default()
+            .block(title)
+            .gauge_style(GAUGE1_COLOR)
+            .percent(self.progress1)
+            .render(area, buf);
+    }
+
+    fn render_gauge2(&self, area: Rect, buf: &mut Buffer) {
+        let title = title_block("Gauge with ratio and custom label");
+        let label = Span::styled(
+            format!("{:.1}/100", self.progress2),
+            Style::new().italic().bold().fg(CUSTOM_LABEL_COLOR),
+        );
+        Gauge::default()
+            .block(title)
+            .gauge_style(GAUGE2_COLOR)
+            .ratio(self.progress2 / 100.0)
+            .label(label)
+            .render(area, buf);
+    }
+
+    fn render_gauge3(&self, area: Rect, buf: &mut Buffer) {
+        let title = title_block("Gauge with ratio (no unicode)");
+        let label = format!("{:.1}%", self.progress3);
+        Gauge::default()
+            .block(title)
+            .gauge_style(GAUGE3_COLOR)
+            .ratio(self.progress3 / 100.0)
+            .label(label)
+            .render(area, buf);
+    }
+
+    fn render_gauge4(&self, area: Rect, buf: &mut Buffer) {
+        let title = title_block("Gauge with ratio (unicode)");
+        let label = format!("{:.1}%", self.progress3);
+        Gauge::default()
+            .block(title)
+            .gauge_style(GAUGE4_COLOR)
+            .ratio(self.progress4 / 100.0)
+            .label(label)
+            .use_unicode(true)
+            .render(area, buf);
+    }
+}
+
+fn title_block(title: &str) -> Block {
+    let title = Title::from(title).alignment(Alignment::Center);
+    Block::new()
+        .borders(Borders::NONE)
+        .padding(Padding::vertical(1))
+        .title(title)
+        .fg(CUSTOM_LABEL_COLOR)
 }
--- a/examples/hello_world.rs
+++ b/examples/hello_world.rs
@@ -0,0 +1,72 @@
+//! # [Ratatui] Hello World example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+use std::time::Duration;
+
+use color_eyre::{eyre::Context, Result};
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode},
+    widgets::Paragraph,
+    DefaultTerminal, Frame,
+};
+
+/// 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.
+///
+/// This example does not handle events or update the application state. It just draws a greeting
+/// and exits when the user presses 'q'.
+fn main() -> Result<()> {
+    color_eyre::install()?; // augment errors / panics with easy to read messages
+    let terminal = ratatui::init();
+    let app_result = run(terminal).context("app loop failed");
+    ratatui::restore();
+    app_result
+}
+
+/// 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(mut terminal: DefaultTerminal) -> Result<()> {
+    loop {
+        terminal.draw(draw)?;
+        if should_quit()? {
+            break;
+        }
+    }
+    Ok(())
+}
+
+/// Render the application. This is where you would draw the application UI. This example draws a
+/// greeting.
+fn draw(frame: &mut Frame) {
+    let greeting = Paragraph::new("Hello World! (press 'q' to quit)");
+    frame.render_widget(greeting, frame.area());
+}
+
+/// 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 to ensure that the terminal is rendered at
+/// least once every 250ms. This allows you to do other work in the application loop, such as
+/// updating the application state, without blocking the event loop for too long.
+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/hyperlink.rs
+++ b/examples/hyperlink.rs
@@ -0,0 +1,101 @@
+//! # [Ratatui] Hyperlink examplew
+//!
+//! Shows how to use [OSC 8] to create hyperlinks in the terminal.
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [OSC 8]: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+use color_eyre::Result;
+use itertools::Itertools;
+use ratatui::{
+    buffer::Buffer,
+    crossterm::event::{self, Event, KeyCode},
+    layout::Rect,
+    style::Stylize,
+    text::{Line, Text},
+    widgets::Widget,
+    DefaultTerminal,
+};
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
+struct App {
+    hyperlink: Hyperlink<'static>,
+}
+
+impl App {
+    fn new() -> Self {
+        let text = Line::from(vec!["Example ".into(), "hyperlink".blue()]);
+        let hyperlink = Hyperlink::new(text, "https://example.com");
+        Self { hyperlink }
+    }
+
+    fn run(self, mut terminal: DefaultTerminal) -> Result<()> {
+        loop {
+            terminal.draw(|frame| frame.render_widget(&self.hyperlink, frame.area()))?;
+            if let Event::Key(key) = event::read()? {
+                if matches!(key.code, KeyCode::Char('q') | KeyCode::Esc) {
+                    break;
+                }
+            }
+        }
+        Ok(())
+    }
+}
+
+/// A hyperlink widget that renders a hyperlink in the terminal using [OSC 8].
+///
+/// [OSC 8]: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
+struct Hyperlink<'content> {
+    text: Text<'content>,
+    url: String,
+}
+
+impl<'content> Hyperlink<'content> {
+    fn new(text: impl Into<Text<'content>>, url: impl Into<String>) -> Self {
+        Self {
+            text: text.into(),
+            url: url.into(),
+        }
+    }
+}
+
+impl Widget for &Hyperlink<'_> {
+    fn render(self, area: Rect, buffer: &mut Buffer) {
+        (&self.text).render(area, buffer);
+
+        // this is a hacky workaround for https://github.com/ratatui/ratatui/issues/902, a bug
+        // in the terminal code that incorrectly calculates the width of ANSI escape sequences. It
+        // works by rendering the hyperlink as a series of 2-character chunks, which is the
+        // calculated width of the hyperlink text.
+        for (i, two_chars) in self
+            .text
+            .to_string()
+            .chars()
+            .chunks(2)
+            .into_iter()
+            .enumerate()
+        {
+            let text = two_chars.collect::<String>();
+            let hyperlink = format!("\x1B]8;;{}\x07{}\x1B]8;;\x07", self.url, text);
+            buffer[(area.x + i as u16 * 2, area.y)].set_symbol(hyperlink.as_str());
+        }
+    }
+}
--- a/examples/inline.rs
+++ b/examples/inline.rs
@@ -0,0 +1,292 @@
+//! # [Ratatui] Inline example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+use std::{
+    collections::{BTreeMap, VecDeque},
+    sync::mpsc,
+    thread,
+    time::{Duration, Instant},
+};
+
+use color_eyre::Result;
+use rand::distributions::{Distribution, Uniform};
+use ratatui::{
+    backend::Backend,
+    crossterm::event,
+    layout::{Alignment, Constraint, Layout, Rect},
+    style::{Color, Modifier, Style},
+    symbols,
+    text::{Line, Span},
+    widgets::{block, Block, Gauge, LineGauge, List, ListItem, Paragraph, Widget},
+    Frame, Terminal, TerminalOptions, Viewport,
+};
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let mut terminal = ratatui::init_with_options(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();
+    }
+
+    let app_result = run(&mut terminal, workers, downloads, rx);
+
+    ratatui::restore();
+
+    app_result
+}
+
+const NUM_DOWNLOADS: usize = 10;
+
+type DownloadId = usize;
+type WorkerId = usize;
+enum Event {
+    Input(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 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 event::poll(timeout).unwrap() {
+                match event::read().unwrap() {
+                    event::Event::Key(key) => tx.send(Event::Input(key)).unwrap(),
+                    event::Event::Resize(_, _) => tx.send(Event::Resize).unwrap(),
+                    _ => {}
+                };
+            }
+            if last_tick.elapsed() >= tick_rate {
+                tx.send(Event::Tick).unwrap();
+                last_tick = Instant::now();
+            }
+        }
+    });
+}
+
+#[allow(clippy::cast_precision_loss, clippy::needless_pass_by_value)]
+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(),
+    }
+}
+
+#[allow(clippy::needless_pass_by_value)]
+fn run(
+    terminal: &mut Terminal<impl Backend>,
+    workers: Vec<Worker>,
+    mut downloads: Downloads,
+    rx: mpsc::Receiver<Event>,
+) -> Result<()> {
+    let mut redraw = true;
+    loop {
+        if redraw {
+            terminal.draw(|frame| draw(frame, &downloads))?;
+        }
+        redraw = true;
+
+        match rx.recv()? {
+            Event::Input(event) => {
+                if event.code == 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 draw(frame: &mut Frame, downloads: &Downloads) {
+    let area = frame.area();
+
+    let block = Block::new().title(block::Title::from("Progress").alignment(Alignment::Center));
+    frame.render_widget(block, area);
+
+    let vertical = Layout::vertical([Constraint::Length(2), Constraint::Length(4)]).margin(1);
+    let horizontal = Layout::horizontal([Constraint::Percentage(20), Constraint::Percentage(80)]);
+    let [progress_area, main] = vertical.areas(area);
+    let [list_area, gauge_area] = horizontal.areas(main);
+
+    // total progress
+    let done = NUM_DOWNLOADS - downloads.pending.len() - downloads.in_progress.len();
+    #[allow(clippy::cast_precision_loss)]
+    let progress = LineGauge::default()
+        .filled_style(Style::default().fg(Color::Blue))
+        .label(format!("{done}/{NUM_DOWNLOADS}"))
+        .ratio(done as f64 / NUM_DOWNLOADS as f64);
+    frame.render_widget(progress, progress_area);
+
+    // 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);
+    frame.render_widget(list, list_area);
+
+    #[allow(clippy::cast_possible_truncation)]
+    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 gauge_area.top().saturating_add(i as u16) > area.bottom() {
+            continue;
+        }
+        frame.render_widget(
+            gauge,
+            Rect {
+                x: gauge_area.left(),
+                y: gauge_area.top().saturating_add(i as u16),
+                width: gauge_area.width,
+                height: 1,
+            },
+        );
+    }
+}
--- a/examples/layout.rs
+++ b/examples/layout.rs
@@ -0,0 +1,206 @@
+//! # [Ratatui] Layout example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+use itertools::Itertools;
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{
+        Constraint::{self, Length, Max, Min, Percentage, Ratio},
+        Layout, Rect,
+    },
+    style::{Color, Style, Stylize},
+    text::Line,
+    widgets::{Block, Paragraph},
+    DefaultTerminal, Frame,
+};
+
+fn main() -> color_eyre::Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = run(terminal);
+    ratatui::restore();
+    app_result
+}
+
+fn run(mut terminal: DefaultTerminal) -> color_eyre::Result<()> {
+    loop {
+        terminal.draw(draw)?;
+        if let Event::Key(key) = event::read()? {
+            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                break Ok(());
+            }
+        }
+    }
+}
+
+#[allow(clippy::too_many_lines)]
+fn draw(frame: &mut Frame) {
+    let vertical = Layout::vertical([
+        Length(4),  // text
+        Length(50), // examples
+        Min(0),     // fills remaining space
+    ]);
+    let [text_area, examples_area, _] = vertical.areas(frame.area());
+
+    // title
+    frame.render_widget(
+        Paragraph::new(vec![
+            Line::from("Horizontal Layout Example. Press q to quit".dark_gray()).centered(),
+            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"),
+        ]),
+        text_area,
+    );
+
+    let example_rows = Layout::vertical([
+        Length(9),
+        Length(9),
+        Length(9),
+        Length(9),
+        Length(9),
+        Min(0), // fills remaining space
+    ])
+    .split(examples_area);
+    let example_areas = example_rows
+        .iter()
+        .flat_map(|area| {
+            Layout::horizontal([
+                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::bordered()
+        .title(title.gray())
+        .style(Style::reset())
+        .border_style(Style::default().fg(Color::DarkGray));
+    let inner = block.inner(area);
+    frame.render_widget(block, area);
+    let layout = Layout::vertical(vec![Length(1); constraints.len() + 1]).split(inner);
+    for (i, (a, b)) in constraints.into_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 horizontal = Layout::horizontal(constraints);
+    let [r, b, g] = horizontal.areas(area);
+    frame.render_widget(red, r);
+    frame.render_widget(blue, b);
+    frame.render_widget(green, g);
+}
+
+fn constraint_label(constraint: Constraint) -> String {
+    match constraint {
+        Constraint::Ratio(a, b) => format!("{a}:{b}"),
+        Constraint::Length(n)
+        | Constraint::Min(n)
+        | Constraint::Max(n)
+        | Constraint::Percentage(n)
+        | Constraint::Fill(n) => format!("{n}"),
+    }
+}
--- a/examples/line_gauge.rs
+++ b/examples/line_gauge.rs
@@ -0,0 +1,179 @@
+//! # [Ratatui] Line Gauge example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+use std::time::Duration;
+
+use color_eyre::Result;
+use ratatui::{
+    buffer::Buffer,
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Alignment, Constraint, Layout, Rect},
+    style::{palette::tailwind, Color, Style, Stylize},
+    widgets::{block::Title, Block, Borders, LineGauge, Padding, Paragraph, Widget},
+    DefaultTerminal,
+};
+
+const CUSTOM_LABEL_COLOR: Color = tailwind::SLATE.c200;
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
+#[derive(Debug, Default, Clone, Copy)]
+struct App {
+    state: AppState,
+    progress_columns: u16,
+    progress: f64,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+enum AppState {
+    #[default]
+    Running,
+    Started,
+    Quitting,
+}
+
+impl App {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        while self.state != AppState::Quitting {
+            terminal.draw(|frame| frame.render_widget(&self, frame.area()))?;
+            self.handle_events()?;
+            self.update(terminal.size()?.width);
+        }
+        Ok(())
+    }
+
+    fn update(&mut self, terminal_width: u16) {
+        if self.state != AppState::Started {
+            return;
+        }
+
+        self.progress_columns = (self.progress_columns + 1).clamp(0, terminal_width);
+        self.progress = f64::from(self.progress_columns) / f64::from(terminal_width);
+    }
+
+    fn handle_events(&mut self) -> Result<()> {
+        let timeout = Duration::from_secs_f32(1.0 / 20.0);
+        if event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                if key.kind == KeyEventKind::Press {
+                    match key.code {
+                        KeyCode::Char(' ') | KeyCode::Enter => self.start(),
+                        KeyCode::Char('q') | KeyCode::Esc => self.quit(),
+                        _ => {}
+                    }
+                }
+            }
+        }
+        Ok(())
+    }
+
+    fn start(&mut self) {
+        self.state = AppState::Started;
+    }
+
+    fn quit(&mut self) {
+        self.state = AppState::Quitting;
+    }
+}
+
+impl Widget for &App {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        use Constraint::{Length, Min, Ratio};
+        let layout = Layout::vertical([Length(2), Min(0), Length(1)]);
+        let [header_area, main_area, footer_area] = layout.areas(area);
+
+        let layout = Layout::vertical([Ratio(1, 3); 3]);
+        let [gauge1_area, gauge2_area, gauge3_area] = layout.areas(main_area);
+
+        header().render(header_area, buf);
+        footer().render(footer_area, buf);
+
+        self.render_gauge1(gauge1_area, buf);
+        self.render_gauge2(gauge2_area, buf);
+        self.render_gauge3(gauge3_area, buf);
+    }
+}
+
+fn header() -> impl Widget {
+    Paragraph::new("Ratatui Line Gauge Example")
+        .bold()
+        .alignment(Alignment::Center)
+        .fg(CUSTOM_LABEL_COLOR)
+}
+
+fn footer() -> impl Widget {
+    Paragraph::new("Press ENTER / SPACE to start")
+        .alignment(Alignment::Center)
+        .fg(CUSTOM_LABEL_COLOR)
+        .bold()
+}
+
+impl App {
+    fn render_gauge1(&self, area: Rect, buf: &mut Buffer) {
+        let title = title_block("Blue / red only foreground");
+        LineGauge::default()
+            .block(title)
+            .filled_style(Style::default().fg(Color::Blue))
+            .unfilled_style(Style::default().fg(Color::Red))
+            .label("Foreground:")
+            .ratio(self.progress)
+            .render(area, buf);
+    }
+
+    fn render_gauge2(&self, area: Rect, buf: &mut Buffer) {
+        let title = title_block("Blue / red only background");
+        LineGauge::default()
+            .block(title)
+            .filled_style(Style::default().fg(Color::Blue).bg(Color::Blue))
+            .unfilled_style(Style::default().fg(Color::Red).bg(Color::Red))
+            .label("Background:")
+            .ratio(self.progress)
+            .render(area, buf);
+    }
+
+    fn render_gauge3(&self, area: Rect, buf: &mut Buffer) {
+        let title = title_block("Fully styled with background");
+        LineGauge::default()
+            .block(title)
+            .filled_style(
+                Style::default()
+                    .fg(tailwind::BLUE.c400)
+                    .bg(tailwind::BLUE.c600),
+            )
+            .unfilled_style(
+                Style::default()
+                    .fg(tailwind::RED.c400)
+                    .bg(tailwind::RED.c800),
+            )
+            .label("Both:")
+            .ratio(self.progress)
+            .render(area, buf);
+    }
+}
+
+fn title_block(title: &str) -> Block {
+    let title = Title::from(title).alignment(Alignment::Center);
+    Block::default()
+        .title(title)
+        .borders(Borders::NONE)
+        .fg(CUSTOM_LABEL_COLOR)
+        .padding(Padding::vertical(1))
+}
--- a/examples/list.rs
+++ b/examples/list.rs
@@ -1,189 +1,287 @@
-extern crate tui;
-extern crate termion;
+//! # [Ratatui] List example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md

-use std::io;
-use std::thread;
-use std::time;
-use std::sync::mpsc;
+use color_eyre::Result;
+use ratatui::{
+    buffer::Buffer,
+    crossterm::event::{self, Event, KeyCode, KeyEvent, KeyEventKind},
+    layout::{Constraint, Layout, Rect},
+    style::{
+        palette::tailwind::{BLUE, GREEN, SLATE},
+        Color, Modifier, Style, Stylize,
+    },
+    symbols,
+    text::Line,
+    widgets::{
+        Block, Borders, HighlightSpacing, List, ListItem, ListState, Padding, Paragraph,
+        StatefulWidget, Widget, Wrap,
+    },
+    DefaultTerminal,
+};

-use termion::event;
-use termion::input::TermRead;
+const TODO_HEADER_STYLE: Style = Style::new().fg(SLATE.c100).bg(BLUE.c800);
+const NORMAL_ROW_BG: Color = SLATE.c950;
+const ALT_ROW_BG_COLOR: Color = SLATE.c900;
+const SELECTED_STYLE: Style = Style::new().bg(SLATE.c800).add_modifier(Modifier::BOLD);
+const TEXT_FG_COLOR: Color = SLATE.c200;
+const COMPLETED_TEXT_FG_COLOR: Color = GREEN.c500;

-use tui::Terminal;
-use tui::backend::TermionBackend;
-use tui::widgets::{Widget, Block, border, SelectableList, List};
-use tui::layout::{Group, Direction, Size};
-use tui::style::{Style, Color, Modifier};
-
-struct App<'a> {
-    items: Vec<&'a str>,
-    selected: usize,
-    events: Vec<(&'a str, &'a str)>,
-    info_style: Style,
-    warning_style: Style,
-    error_style: Style,
-    critical_style: Style,
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
 }

-impl<'a> App<'a> {
-    fn new() -> App<'a> {
-        App {
-            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: 0,
-            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")],
-            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),
+/// This struct holds the current state of the app. In particular, it has the `todo_list` field
+/// which is a wrapper around `ListState`. Keeping track of the state lets 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 {
+    should_exit: bool,
+    todo_list: TodoList,
+}
+
+struct TodoList {
+    items: Vec<TodoItem>,
+    state: ListState,
+}
+
+#[derive(Debug)]
+struct TodoItem {
+    todo: String,
+    info: String,
+    status: Status,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+enum Status {
+    Todo,
+    Completed,
+}
+
+impl Default for App {
+    fn default() -> Self {
+        Self {
+            should_exit: false,
+            todo_list: TodoList::from_iter([
+                (Status::Todo, "Rewrite everything with Rust!", "I can't hold my inner voice. He tells me to rewrite the complete universe with Rust"),
+                (Status::Completed, "Rewrite all of your tui apps with Ratatui", "Yes, you heard that right. Go and replace your tui with Ratatui."),
+                (Status::Todo, "Pet your cat", "Minnak loves to be pet by you! Don't forget to pet and give some treats!"),
+                (Status::Todo, "Walk with your dog", "Max is bored, go walk with him!"),
+                (Status::Completed, "Pay the bills", "Pay the train subscription!!!"),
+                (Status::Completed, "Refactor list example", "If you see this info that means I completed this task!"),
+            ]),
        }
    }
+}

-    fn advance(&mut self) {
-        let event = self.events.pop().unwrap();
-        self.events.insert(0, event);
+impl FromIterator<(Status, &'static str, &'static str)> for TodoList {
+    fn from_iter<I: IntoIterator<Item = (Status, &'static str, &'static str)>>(iter: I) -> Self {
+        let items = iter
+            .into_iter()
+            .map(|(status, todo, info)| TodoItem::new(status, todo, info))
+            .collect();
+        let state = ListState::default();
+        Self { items, state }
    }
 }

-enum Event {
-    Input(event::Key),
-    Tick,
+impl TodoItem {
+    fn new(status: Status, todo: &str, info: &str) -> Self {
+        Self {
+            status,
+            todo: todo.to_string(),
+            info: info.to_string(),
+        }
+    }
 }

-fn main() {
-    // Terminal initialization
-    let backend = TermionBackend::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;
-            }
+impl App {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        while !self.should_exit {
+            terminal.draw(|frame| frame.render_widget(&mut self, frame.area()))?;
+            if let Event::Key(key) = event::read()? {
+                self.handle_key(key);
+            };
        }
-    });
-
-    // 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();
-    draw(&mut terminal, &app);
-
-    loop {
-        let evt = rx.recv().unwrap();
-        match evt {
-            Event::Input(input) => {
-                match input {
-                    event::Key::Char('q') => {
-                        break;
-                    }
-                    event::Key::Down => {
-                        app.selected += 1;
-                        if app.selected > app.items.len() - 1 {
-                            app.selected = 0;
-                        }
-                    }
-                    event::Key::Up => {
-                        if app.selected > 0 {
-                            app.selected -= 1;
-                        } else {
-                            app.selected = app.items.len() - 1;
-                        }
-                    }
-                    _ => {}
-                }
-            }
-            Event::Tick => {
-                app.advance();
-            }
-        }
-        draw(&mut terminal, &app);
+        Ok(())
    }

-    terminal.show_cursor().unwrap();
+    fn handle_key(&mut self, key: KeyEvent) {
+        if key.kind != KeyEventKind::Press {
+            return;
+        }
+        match key.code {
+            KeyCode::Char('q') | KeyCode::Esc => self.should_exit = true,
+            KeyCode::Char('h') | KeyCode::Left => self.select_none(),
+            KeyCode::Char('j') | KeyCode::Down => self.select_next(),
+            KeyCode::Char('k') | KeyCode::Up => self.select_previous(),
+            KeyCode::Char('g') | KeyCode::Home => self.select_first(),
+            KeyCode::Char('G') | KeyCode::End => self.select_last(),
+            KeyCode::Char('l') | KeyCode::Right | KeyCode::Enter => {
+                self.toggle_status();
+            }
+            _ => {}
+        }
+    }
+
+    fn select_none(&mut self) {
+        self.todo_list.state.select(None);
+    }
+
+    fn select_next(&mut self) {
+        self.todo_list.state.select_next();
+    }
+    fn select_previous(&mut self) {
+        self.todo_list.state.select_previous();
+    }
+
+    fn select_first(&mut self) {
+        self.todo_list.state.select_first();
+    }
+
+    fn select_last(&mut self) {
+        self.todo_list.state.select_last();
+    }
+
+    /// Changes the status of the selected list item
+    fn toggle_status(&mut self) {
+        if let Some(i) = self.todo_list.state.selected() {
+            self.todo_list.items[i].status = match self.todo_list.items[i].status {
+                Status::Completed => Status::Todo,
+                Status::Todo => Status::Completed,
+            }
+        }
+    }
 }

-fn draw(t: &mut Terminal<TermionBackend>, app: &App) {
+impl Widget for &mut App {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let [header_area, main_area, footer_area] = Layout::vertical([
+            Constraint::Length(2),
+            Constraint::Fill(1),
+            Constraint::Length(1),
+        ])
+        .areas(area);

-    let size = t.size().unwrap();
+        let [list_area, item_area] =
+            Layout::vertical([Constraint::Fill(1), Constraint::Fill(1)]).areas(main_area);

-    Group::default()
-        .direction(Direction::Horizontal)
-        .sizes(&[Size::Percent(50), Size::Percent(50)])
-        .render(t, &size, |t, chunks| {
-            SelectableList::default()
-                .block(Block::default()
-                    .borders(border::ALL)
-                    .title("List"))
-                .items(&app.items)
-                .select(app.selected)
-                .highlight_style(Style::default().fg(Color::Yellow).modifier(Modifier::Bold))
-                .highlight_symbol(">")
-                .render(t, &chunks[0]);
-            List::default()
-                .block(Block::default()
-                    .borders(border::ALL)
-                    .title("List"))
-                .items(&app.events
-                    .iter()
-                    .map(|&(evt, level)| {
-                        (format!("{}: {}", level, evt),
-                         match level {
-                            "ERROR" => &app.error_style,
-                            "CRITICAL" => &app.critical_style,
-                            "WARNING" => &app.warning_style,
-                            _ => &app.info_style,
-                        })
-                    })
-                    .collect::<Vec<(String, &Style)>>())
-                .render(t, &chunks[1]);
-        });
-
-    t.draw().unwrap();
+        App::render_header(header_area, buf);
+        App::render_footer(footer_area, buf);
+        self.render_list(list_area, buf);
+        self.render_selected_item(item_area, buf);
+    }
+}
+
+/// Rendering logic for the app
+impl App {
+    fn render_header(area: Rect, buf: &mut Buffer) {
+        Paragraph::new("Ratatui List Example")
+            .bold()
+            .centered()
+            .render(area, buf);
+    }
+
+    fn render_footer(area: Rect, buf: &mut Buffer) {
+        Paragraph::new("Use ↓↑ to move, ← to unselect, → to change status, g/G to go top/bottom.")
+            .centered()
+            .render(area, buf);
+    }
+
+    fn render_list(&mut self, area: Rect, buf: &mut Buffer) {
+        let block = Block::new()
+            .title(Line::raw("TODO List").centered())
+            .borders(Borders::TOP)
+            .border_set(symbols::border::EMPTY)
+            .border_style(TODO_HEADER_STYLE)
+            .bg(NORMAL_ROW_BG);
+
+        // Iterate through all elements in the `items` and stylize them.
+        let items: Vec<ListItem> = self
+            .todo_list
+            .items
+            .iter()
+            .enumerate()
+            .map(|(i, todo_item)| {
+                let color = alternate_colors(i);
+                ListItem::from(todo_item).bg(color)
+            })
+            .collect();
+
+        // Create a List from all list items and highlight the currently selected one
+        let list = List::new(items)
+            .block(block)
+            .highlight_style(SELECTED_STYLE)
+            .highlight_symbol(">")
+            .highlight_spacing(HighlightSpacing::Always);
+
+        // We need to disambiguate this trait method as both `Widget` and `StatefulWidget` share the
+        // same method name `render`.
+        StatefulWidget::render(list, area, buf, &mut self.todo_list.state);
+    }
+
+    fn render_selected_item(&self, area: Rect, buf: &mut Buffer) {
+        // We get the info depending on the item's state.
+        let info = if let Some(i) = self.todo_list.state.selected() {
+            match self.todo_list.items[i].status {
+                Status::Completed => format!("✓ DONE: {}", self.todo_list.items[i].info),
+                Status::Todo => format!("☐ TODO: {}", self.todo_list.items[i].info),
+            }
+        } else {
+            "Nothing selected...".to_string()
+        };
+
+        // We show the list item's info under the list in this paragraph
+        let block = Block::new()
+            .title(Line::raw("TODO Info").centered())
+            .borders(Borders::TOP)
+            .border_set(symbols::border::EMPTY)
+            .border_style(TODO_HEADER_STYLE)
+            .bg(NORMAL_ROW_BG)
+            .padding(Padding::horizontal(1));
+
+        // We can now render the item info
+        Paragraph::new(info)
+            .block(block)
+            .fg(TEXT_FG_COLOR)
+            .wrap(Wrap { trim: false })
+            .render(area, buf);
+    }
+}
+
+const fn alternate_colors(i: usize) -> Color {
+    if i % 2 == 0 {
+        NORMAL_ROW_BG
+    } else {
+        ALT_ROW_BG_COLOR
+    }
+}
+
+impl From<&TodoItem> for ListItem<'_> {
+    fn from(value: &TodoItem) -> Self {
+        let line = match value.status {
+            Status::Todo => Line::styled(format!(" ☐ {}", value.todo), TEXT_FG_COLOR),
+            Status::Completed => {
+                Line::styled(format!(" ✓ {}", value.todo), COMPLETED_TEXT_FG_COLOR)
+            }
+        };
+        ListItem::new(line)
+    }
 }
--- a/examples/minimal.rs
+++ b/examples/minimal.rs
@@ -0,0 +1,40 @@
+//! # [Ratatui] Minimal example
+//!
+//! This is a bare minimum example. There are many approaches to running an application loop, so
+//! this is not meant to be prescriptive. See the [examples] folder for more complete examples.
+//! In particular, the [hello-world] example is a good starting point.
+//!
+//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
+//! [hello-world]: https://github.com/ratatui-org/ratatui/blob/main/examples/hello_world.rs
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+use ratatui::{
+    crossterm::event::{self, Event},
+    text::Text,
+    Frame,
+};
+
+fn main() {
+    let mut terminal = ratatui::init();
+    loop {
+        terminal
+            .draw(|frame: &mut Frame| frame.render_widget(Text::raw("Hello World!"), frame.area()))
+            .expect("Failed to draw");
+        if matches!(event::read().expect("failed to read event"), Event::Key(_)) {
+            break;
+        }
+    }
+    ratatui::restore();
+}
--- a/examples/modifiers.rs
+++ b/examples/modifiers.rs
@@ -0,0 +1,100 @@
+//! # [Ratatui] Modifiers example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+// 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, iter::once, result};
+
+use itertools::Itertools;
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Constraint, Layout},
+    style::{Color, Modifier, Style, Stylize},
+    text::Line,
+    widgets::Paragraph,
+    DefaultTerminal, Frame,
+};
+
+type Result<T> = result::Result<T, Box<dyn Error>>;
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = run(terminal);
+    ratatui::restore();
+    app_result
+}
+
+fn run(mut terminal: DefaultTerminal) -> Result<()> {
+    loop {
+        terminal.draw(draw)?;
+        if let Event::Key(key) = event::read()? {
+            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                return Ok(());
+            }
+        }
+    }
+}
+
+fn draw(frame: &mut Frame) {
+    let vertical = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
+    let [text_area, main_area] = vertical.areas(frame.area());
+    frame.render_widget(
+        Paragraph::new("Note: not all terminals support all modifiers")
+            .style(Style::default().fg(Color::Red).add_modifier(Modifier::BOLD)),
+        text_area,
+    );
+    let layout = Layout::vertical([Constraint::Length(1); 50])
+        .split(main_area)
+        .iter()
+        .flat_map(|area| {
+            Layout::horizontal([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 {
+        for fg in &colors {
+            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;
+            }
+        }
+    }
+}
--- a/examples/panic.rs
+++ b/examples/panic.rs
@@ -0,0 +1,110 @@
+//! # [Ratatui] Panic Hook example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+//!
+//! Prior to Ratatui 0.28.1, a panic hook had to be manually set up to ensure that the terminal was
+//! reset when a panic occurred. This was necessary because a panic would interrupt the normal
+//! control flow and leave the terminal in a distorted state.
+//!
+//! Starting with Ratatui 0.28.1, the panic hook is automatically set up by the new `ratatui::init`
+//! function, so you no longer need to manually set up the panic hook. This example now demonstrates
+//! how the panic hook acts when it is enabled by default.
+//!
+//! 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 panic hook, to
+//! see the difference.
+//!
+//! For more information on how to set this up manually, see the [Color Eyre recipe] in the Ratatui
+//! website.
+//!
+//! [Color Eyre recipe]: https://ratatui.rs/recipes/apps/color-eyre
+
+use color_eyre::{eyre::bail, Result};
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode},
+    text::Line,
+    widgets::{Block, Paragraph},
+    DefaultTerminal, Frame,
+};
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
+}
+struct App {
+    hook_enabled: bool,
+}
+
+impl App {
+    const fn new() -> Self {
+        Self { hook_enabled: true }
+    }
+
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        loop {
+            terminal.draw(|frame| self.draw(frame))?;
+
+            if let Event::Key(key) = event::read()? {
+                match key.code {
+                    KeyCode::Char('p') => panic!("intentional demo panic"),
+                    KeyCode::Char('e') => bail!("intentional demo error"),
+                    KeyCode::Char('h') => {
+                        let _ = std::panic::take_hook();
+                        self.hook_enabled = false;
+                    }
+                    KeyCode::Char('q') => return Ok(()),
+                    _ => {}
+                }
+            }
+        }
+    }
+
+    fn draw(&self, frame: &mut Frame) {
+        let text = vec![
+            if self.hook_enabled {
+                Line::from("HOOK IS CURRENTLY **ENABLED**")
+            } else {
+                Line::from("HOOK IS CURRENTLY **DISABLED**")
+            },
+            Line::from(""),
+            Line::from("Press `p` to cause a panic"),
+            Line::from("Press `e` to cause an error"),
+            Line::from("Press `h` to disable the panic hook"),
+            Line::from("Press `q` to quit"),
+            Line::from(""),
+            Line::from("When your app panics without a panic hook, you will likely have to"),
+            Line::from("reset your terminal afterwards with the `reset` command"),
+            Line::from(""),
+            Line::from("Try first with the panic handler enabled, and then with it disabled"),
+            Line::from("to see the difference"),
+        ];
+
+        let paragraph = Paragraph::new(text)
+            .block(Block::bordered().title("Panic Handler Demo"))
+            .centered();
+
+        frame.render_widget(paragraph, frame.area());
+    }
+}
--- a/examples/paragraph.rs
+++ b/examples/paragraph.rs
@@ -1,58 +1,153 @@
-extern crate tui;
-extern crate termion;
+//! # [Ratatui] Paragraph example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md

-use std::io;
-use termion::event;
-use termion::input::TermRead;
+use std::{
+    io::{self},
+    time::{Duration, Instant},
+};

-use tui::Terminal;
-use tui::backend::TermionBackend;
-use tui::widgets::{Widget, Block, Paragraph};
-use tui::layout::{Group, Direction, Size};
-use tui::style::{Style, Color};
+use color_eyre::Result;
+use ratatui::{
+    buffer::Buffer,
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Constraint, Layout, Rect},
+    style::{Color, Stylize},
+    text::{Line, Masked, Span},
+    widgets::{Block, Paragraph, Widget, Wrap},
+    DefaultTerminal,
+};

-fn main() {
-    let mut terminal = Terminal::new(TermionBackend::new().unwrap()).unwrap();
-    let stdin = io::stdin();
-    terminal.clear().unwrap();
-    terminal.hide_cursor().unwrap();
-    draw(&mut terminal);
-    for c in stdin.keys() {
-        draw(&mut terminal);
-        let evt = c.unwrap();
-        if evt == event::Key::Char('q') {
-            break;
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
+#[derive(Debug)]
+struct App {
+    should_exit: bool,
+    scroll: u16,
+    last_tick: Instant,
+}
+
+impl App {
+    /// The duration between each tick.
+    const TICK_RATE: Duration = Duration::from_millis(250);
+
+    /// Create a new instance of the app.
+    fn new() -> Self {
+        Self {
+            should_exit: false,
+            scroll: 0,
+            last_tick: Instant::now(),
        }
    }
-    terminal.show_cursor().unwrap();
+
+    /// Run the app until the user exits.
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        while !self.should_exit {
+            terminal.draw(|frame| frame.render_widget(&self, frame.area()))?;
+            self.handle_events()?;
+            if self.last_tick.elapsed() >= Self::TICK_RATE {
+                self.on_tick();
+                self.last_tick = Instant::now();
+            }
+        }
+        Ok(())
+    }
+
+    /// Handle events from the terminal.
+    fn handle_events(&mut self) -> io::Result<()> {
+        let timeout = Self::TICK_RATE.saturating_sub(self.last_tick.elapsed());
+        while event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
+                    self.should_exit = true;
+                }
+            }
+        }
+        Ok(())
+    }
+
+    /// Update the app state on each tick.
+    fn on_tick(&mut self) {
+        self.scroll = (self.scroll + 1) % 10;
+    }
 }

-fn draw(t: &mut Terminal<TermionBackend>) {
-
-    let size = t.size().unwrap();
-
-    Block::default()
-        .style(Style::default().bg(Color::White))
-        .render(t, &size);
-
-    Group::default()
-        .direction(Direction::Vertical)
-        .margin(5)
-        .sizes(&[Size::Percent(100)])
-        .render(t, &size, |t, chunks| {
-            Group::default()
-                .direction(Direction::Horizontal)
-                .sizes(&[Size::Percent(100)])
-                .render(t, &chunks[0], |t, chunks| {
-                    Paragraph::default()
-                        .text("This is a line\n{fg=red This is a line}\n{bg=red This is a \
-                               line}\n{mod=italic This is a line}\n{mod=bold This is a \
-                               line}\n{mod=crossed_out This is a line}\n{mod=invert This is a \
-                               line}\n{mod=underline This is a \
-                               line}\n{bg=green;fg=yellow;mod=italic This is a line}\n")
-                        .render(t, &chunks[0]);
-                });
-        });
-
-    t.draw().unwrap();
+impl Widget for &App {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let areas = Layout::vertical([Constraint::Max(9); 4]).split(area);
+        Paragraph::new(create_lines(area))
+            .block(title_block("Default alignment (Left), no wrap"))
+            .gray()
+            .render(areas[0], buf);
+        Paragraph::new(create_lines(area))
+            .block(title_block("Default alignment (Left), with wrap"))
+            .gray()
+            .wrap(Wrap { trim: true })
+            .render(areas[1], buf);
+        Paragraph::new(create_lines(area))
+            .block(title_block("Right alignment, with wrap"))
+            .gray()
+            .right_aligned()
+            .wrap(Wrap { trim: true })
+            .render(areas[2], buf);
+        Paragraph::new(create_lines(area))
+            .block(title_block("Center alignment, with wrap, with scroll"))
+            .gray()
+            .centered()
+            .wrap(Wrap { trim: true })
+            .scroll((self.scroll, 0))
+            .render(areas[3], buf);
+    }
+}
+
+/// Create a bordered block with a title.
+fn title_block(title: &str) -> Block {
+    Block::bordered()
+        .gray()
+        .title(title.bold().into_centered_line())
+}
+
+/// Create some lines to display in the paragraph.
+fn create_lines(area: Rect) -> Vec<Line<'static>> {
+    let short_line = "A long line to demonstrate line wrapping. ";
+    let long_line = short_line.repeat(usize::from(area.width) / short_line.len() + 4);
+    let mut styled_spans = vec![];
+    for span in [
+        "Styled".blue(),
+        "Spans".red().on_white(),
+        "Bold".bold(),
+        "Italic".italic(),
+        "Underlined".underlined(),
+        "Strikethrough".crossed_out(),
+    ] {
+        styled_spans.push(span);
+        styled_spans.push(" ".into());
+    }
+    vec![
+        Line::raw("Unstyled Line"),
+        Line::raw("Styled Line").black().on_red().bold().italic(),
+        Line::from(styled_spans),
+        Line::from(long_line.green().italic()),
+        Line::from_iter([
+            "Masked text: ".into(),
+            Span::styled(Masked::new("my secret password", '*'), Color::Red),
+        ]),
+    ]
 }
--- a/examples/popup.rs
+++ b/examples/popup.rs
@@ -0,0 +1,93 @@
+//! # [Ratatui] Popup example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+// See also https://github.com/joshka/tui-popup and
+// https://github.com/sephiroth74/tui-confirm-dialog
+
+use color_eyre::Result;
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Constraint, Flex, Layout, Rect},
+    style::Stylize,
+    widgets::{Block, Clear, Paragraph, Wrap},
+    DefaultTerminal, Frame,
+};
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
+#[derive(Default)]
+struct App {
+    show_popup: bool,
+}
+
+impl App {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        loop {
+            terminal.draw(|frame| self.draw(frame))?;
+
+            if let Event::Key(key) = event::read()? {
+                if key.kind == KeyEventKind::Press {
+                    match key.code {
+                        KeyCode::Char('q') => return Ok(()),
+                        KeyCode::Char('p') => self.show_popup = !self.show_popup,
+                        _ => {}
+                    }
+                }
+            }
+        }
+    }
+
+    fn draw(&self, frame: &mut Frame) {
+        let area = frame.area();
+
+        let vertical = Layout::vertical([Constraint::Percentage(20), Constraint::Percentage(80)]);
+        let [instructions, content] = vertical.areas(area);
+
+        let text = if self.show_popup {
+            "Press p to close the popup"
+        } else {
+            "Press p to show the popup"
+        };
+        let paragraph = Paragraph::new(text.slow_blink())
+            .centered()
+            .wrap(Wrap { trim: true });
+        frame.render_widget(paragraph, instructions);
+
+        let block = Block::bordered().title("Content").on_blue();
+        frame.render_widget(block, content);
+
+        if self.show_popup {
+            let block = Block::bordered().title("Popup");
+            let area = popup_area(area, 60, 20);
+            frame.render_widget(Clear, area); //this clears out the background
+            frame.render_widget(block, area);
+        }
+    }
+}
+
+/// helper function to create a centered rect using up certain percentage of the available rect `r`
+fn popup_area(area: Rect, percent_x: u16, percent_y: u16) -> Rect {
+    let vertical = Layout::vertical([Constraint::Percentage(percent_y)]).flex(Flex::Center);
+    let horizontal = Layout::horizontal([Constraint::Percentage(percent_x)]).flex(Flex::Center);
+    let [area] = vertical.areas(area);
+    let [area] = horizontal.areas(area);
+    area
+}
--- a/examples/ratatui-logo.rs
+++ b/examples/ratatui-logo.rs
@@ -0,0 +1,69 @@
+//! # [Ratatui] Logo example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+use std::{
+    io::{self},
+    thread::sleep,
+    time::Duration,
+};
+
+use indoc::indoc;
+use itertools::izip;
+use ratatui::{widgets::Paragraph, TerminalOptions, Viewport};
+
+/// A fun example of using half block characters to draw a logo
+#[allow(clippy::many_single_char_names)]
+fn logo() -> String {
+    let r = indoc! {"
+            ▄▄▄
+            █▄▄▀
+            █  █
+        "};
+    let a = indoc! {"
+             ▄▄
+            █▄▄█
+            █  █
+        "};
+    let t = indoc! {"
+            ▄▄▄
+             █
+             █
+        "};
+    let u = indoc! {"
+            ▄  ▄
+            █  █
+            ▀▄▄▀
+        "};
+    let i = indoc! {"
+            ▄
+            █
+            █
+        "};
+    izip!(r.lines(), a.lines(), t.lines(), u.lines(), i.lines())
+        .map(|(r, a, t, u, i)| format!("{r:5}{a:5}{t:4}{a:5}{t:4}{u:5}{i:5}"))
+        .collect::<Vec<_>>()
+        .join("\n")
+}
+
+fn main() -> io::Result<()> {
+    let mut terminal = ratatui::init_with_options(TerminalOptions {
+        viewport: Viewport::Inline(3),
+    });
+    terminal.draw(|frame| frame.render_widget(Paragraph::new(logo()), frame.area()))?;
+    sleep(Duration::from_secs(5));
+    ratatui::restore();
+    println!();
+    Ok(())
+}
--- a/examples/rustbox.rs
+++ b/examples/rustbox.rs
@@ -1,52 +0,0 @@
-extern crate tui;
-extern crate rustbox;
-
-use std::error::Error;
-use rustbox::Key;
-
-use tui::Terminal;
-use tui::backend::RustboxBackend;
-use tui::widgets::{Widget, Block, border, Paragraph};
-use tui::layout::{Group, Direction, Size};
-use tui::style::{Style, Color, Modifier};
-
-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();
-
-    Group::default()
-        .direction(Direction::Vertical)
-        .sizes(&[Size::Percent(100)])
-        .render(t, &size, |t, chunks| {
-            Paragraph::default()
-                .block(Block::default()
-                    .title("Rustbox backend")
-                    .title_style(Style::default().fg(Color::Yellow).modifier(Modifier::Bold))
-                    .borders(border::ALL)
-                    .border_style(Style::default().fg(Color::Magenta)))
-                .text("It {yellow works}!")
-                .render(t, &chunks[0]);
-        });
-
-    t.draw().unwrap();
-}
--- a/examples/scrollbar.rs
+++ b/examples/scrollbar.rs
@@ -0,0 +1,211 @@
+//! # [Ratatui] Scrollbar example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+#![warn(clippy::pedantic)]
+
+use std::time::{Duration, Instant};
+
+use color_eyre::Result;
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode},
+    layout::{Alignment, Constraint, Layout, Margin},
+    style::{Color, Style, Stylize},
+    symbols::scrollbar,
+    text::{Line, Masked, Span},
+    widgets::{Block, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState},
+    DefaultTerminal, Frame,
+};
+
+#[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<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::default().run(terminal);
+    ratatui::restore();
+    app_result
+}
+
+impl App {
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        let tick_rate = Duration::from_millis(250);
+        let mut last_tick = Instant::now();
+        loop {
+            terminal.draw(|frame| self.draw(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') => return Ok(()),
+                        KeyCode::Char('j') | KeyCode::Down => {
+                            self.vertical_scroll = self.vertical_scroll.saturating_add(1);
+                            self.vertical_scroll_state =
+                                self.vertical_scroll_state.position(self.vertical_scroll);
+                        }
+                        KeyCode::Char('k') | KeyCode::Up => {
+                            self.vertical_scroll = self.vertical_scroll.saturating_sub(1);
+                            self.vertical_scroll_state =
+                                self.vertical_scroll_state.position(self.vertical_scroll);
+                        }
+                        KeyCode::Char('h') | KeyCode::Left => {
+                            self.horizontal_scroll = self.horizontal_scroll.saturating_sub(1);
+                            self.horizontal_scroll_state = self
+                                .horizontal_scroll_state
+                                .position(self.horizontal_scroll);
+                        }
+                        KeyCode::Char('l') | KeyCode::Right => {
+                            self.horizontal_scroll = self.horizontal_scroll.saturating_add(1);
+                            self.horizontal_scroll_state = self
+                                .horizontal_scroll_state
+                                .position(self.horizontal_scroll);
+                        }
+                        _ => {}
+                    }
+                }
+            }
+            if last_tick.elapsed() >= tick_rate {
+                last_tick = Instant::now();
+            }
+        }
+    }
+
+    #[allow(clippy::too_many_lines, clippy::cast_possible_truncation)]
+    fn draw(&mut self, frame: &mut Frame) {
+        let area = frame.area();
+
+        // Words made "loooong" to demonstrate line breaking.
+        let s =
+            "Veeeeeeeeeeeeeeeery    loooooooooooooooooong   striiiiiiiiiiiiiiiiiiiiiiiiiing.   ";
+        let mut long_line = s.repeat(usize::from(area.width) / s.len() + 4);
+        long_line.push('\n');
+
+        let chunks = Layout::vertical([
+            Constraint::Min(1),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+            Constraint::Percentage(25),
+        ])
+        .split(area);
+
+        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::new().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::new().fg(Color::Red)),
+            ]),
+        ];
+        self.vertical_scroll_state = self.vertical_scroll_state.content_length(text.len());
+        self.horizontal_scroll_state = self.horizontal_scroll_state.content_length(long_line.len());
+
+        let create_block = |title: &'static str| Block::bordered().gray().title(title.bold());
+
+        let title = Block::new()
+            .title_alignment(Alignment::Center)
+            .title("Use h j k l or ◄ ▲ ▼ ► to scroll ".bold());
+        frame.render_widget(title, chunks[0]);
+
+        let paragraph = Paragraph::new(text.clone())
+            .gray()
+            .block(create_block("Vertical scrollbar with arrows"))
+            .scroll((self.vertical_scroll as u16, 0));
+        frame.render_widget(paragraph, chunks[1]);
+        frame.render_stateful_widget(
+            Scrollbar::new(ScrollbarOrientation::VerticalRight)
+                .begin_symbol(Some("↑"))
+                .end_symbol(Some("↓")),
+            chunks[1],
+            &mut self.vertical_scroll_state,
+        );
+
+        let paragraph = Paragraph::new(text.clone())
+            .gray()
+            .block(create_block(
+                "Vertical scrollbar without arrows, without track symbol and mirrored",
+            ))
+            .scroll((self.vertical_scroll as u16, 0));
+        frame.render_widget(paragraph, chunks[2]);
+        frame.render_stateful_widget(
+            Scrollbar::new(ScrollbarOrientation::VerticalLeft)
+                .symbols(scrollbar::VERTICAL)
+                .begin_symbol(None)
+                .track_symbol(None)
+                .end_symbol(None),
+            chunks[2].inner(Margin {
+                vertical: 1,
+                horizontal: 0,
+            }),
+            &mut self.vertical_scroll_state,
+        );
+
+        let paragraph = Paragraph::new(text.clone())
+            .gray()
+            .block(create_block(
+                "Horizontal scrollbar with only begin arrow & custom thumb symbol",
+            ))
+            .scroll((0, self.horizontal_scroll as u16));
+        frame.render_widget(paragraph, chunks[3]);
+        frame.render_stateful_widget(
+            Scrollbar::new(ScrollbarOrientation::HorizontalBottom)
+                .thumb_symbol("🬋")
+                .end_symbol(None),
+            chunks[3].inner(Margin {
+                vertical: 0,
+                horizontal: 1,
+            }),
+            &mut self.horizontal_scroll_state,
+        );
+
+        let paragraph = Paragraph::new(text.clone())
+            .gray()
+            .block(create_block(
+                "Horizontal scrollbar without arrows & custom thumb and track symbol",
+            ))
+            .scroll((0, self.horizontal_scroll as u16));
+        frame.render_widget(paragraph, chunks[4]);
+        frame.render_stateful_widget(
+            Scrollbar::new(ScrollbarOrientation::HorizontalBottom)
+                .thumb_symbol("░")
+                .track_symbol(Some("─")),
+            chunks[4].inner(Margin {
+                vertical: 0,
+                horizontal: 1,
+            }),
+            &mut self.horizontal_scroll_state,
+        );
+    }
+}
--- a/examples/sparkline.rs
+++ b/examples/sparkline.rs
@@ -1,22 +1,40 @@
-extern crate tui;
-extern crate termion;
+//! # [Ratatui] Sparkline example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md

-mod util;
-use util::*;
+use std::time::{Duration, Instant};

-use std::io;
-use std::thread;
-use std::time;
-use std::sync::mpsc;
+use color_eyre::Result;
+use rand::{
+    distributions::{Distribution, Uniform},
+    rngs::ThreadRng,
+};
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode},
+    layout::{Constraint, Layout},
+    style::{Color, Style},
+    widgets::{Block, Borders, Sparkline},
+    DefaultTerminal, Frame,
+};

-use termion::event;
-use termion::input::TermRead;
-
-use tui::Terminal;
-use tui::backend::TermionBackend;
-use tui::widgets::{Widget, Block, border, Sparkline};
-use tui::layout::{Group, Direction, Size};
-use tui::style::{Style, Color};
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
+}

 struct App {
    signal: RandomSignal,
@@ -25,21 +43,43 @@ struct App {
    data3: Vec<u64>,
 }

+#[derive(Clone)]
+struct RandomSignal {
+    distribution: Uniform<u64>,
+    rng: ThreadRng,
+}
+
+impl RandomSignal {
+    fn new(lower: u64, upper: u64) -> Self {
+        Self {
+            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))
+    }
+}
+
 impl App {
-    fn new() -> App {
+    fn new() -> Self {
        let mut signal = RandomSignal::new(0, 100);
        let data1 = signal.by_ref().take(200).collect::<Vec<u64>>();
        let data2 = signal.by_ref().take(200).collect::<Vec<u64>>();
        let data3 = signal.by_ref().take(200).collect::<Vec<u64>>();
-        App {
-            signal: signal,
-            data1: data1,
-            data2: data2,
-            data3: data3,
+        Self {
+            signal,
+            data1,
+            data2,
+            data3,
        }
    }

-    fn advance(&mut self) {
+    fn on_tick(&mut self) {
        let value = self.signal.next().unwrap();
        self.data1.pop();
        self.data1.insert(0, value);
@@ -50,95 +90,63 @@ impl App {
        self.data3.pop();
        self.data3.insert(0, value);
    }
-}

-enum Event {
-    Input(event::Key),
-    Tick,
-}
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        let tick_rate = Duration::from_millis(250);

-fn main() {
-    // Terminal initialization
-    let backend = TermionBackend::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 || {
+        let mut last_tick = Instant::now();
        loop {
-            clock_tx.send(Event::Tick).unwrap();
-            thread::sleep(time::Duration::from_millis(500));
-        }
-    });
+            terminal.draw(|frame| self.draw(frame))?;

-    // App
-    let mut app = App::new();
-
-    // First draw call
-    terminal.clear().unwrap();
-    terminal.hide_cursor().unwrap();
-    draw(&mut terminal, &app);
-
-    loop {
-        let evt = rx.recv().unwrap();
-        match evt {
-            Event::Input(input) => {
-                if input == event::Key::Char('q') {
-                    break;
+            let timeout = tick_rate.saturating_sub(last_tick.elapsed());
+            if event::poll(timeout)? {
+                if let Event::Key(key) = event::read()? {
+                    if key.code == KeyCode::Char('q') {
+                        return Ok(());
+                    }
                }
            }
-            Event::Tick => {
-                app.advance();
+            if last_tick.elapsed() >= tick_rate {
+                self.on_tick();
+                last_tick = Instant::now();
            }
        }
-        draw(&mut terminal, &app);
    }

-    terminal.show_cursor().unwrap();
-}
-
-fn draw(t: &mut Terminal<TermionBackend>, app: &App) {
-
-    let size = t.size().unwrap();
-
-    Group::default()
-        .direction(Direction::Vertical)
-        .margin(2)
-        .sizes(&[Size::Fixed(3), Size::Fixed(3), Size::Fixed(7), Size::Min(0)])
-        .render(t, &size, |t, chunks| {
-            Sparkline::default()
-                .block(Block::default().title("Data1").borders(border::LEFT | border::RIGHT))
-                .data(&app.data1)
-                .style(Style::default().fg(Color::Yellow))
-                .render(t, &chunks[0]);
-            Sparkline::default()
-                .block(Block::default().title("Data2").borders(border::LEFT | border::RIGHT))
-                .data(&app.data2)
-                .style(Style::default().bg(Color::Green))
-                .render(t, &chunks[1]);
-            // Multiline
-            Sparkline::default()
-                .block(Block::default().title("Data3").borders(border::LEFT | border::RIGHT))
-                .data(&app.data3)
-                .style(Style::default().fg(Color::Red))
-                .render(t, &chunks[2]);
-        });
-
-    t.draw().unwrap();
+    fn draw(&self, frame: &mut Frame) {
+        let chunks = Layout::vertical([
+            Constraint::Length(3),
+            Constraint::Length(3),
+            Constraint::Min(0),
+        ])
+        .split(frame.area());
+        let sparkline = Sparkline::default()
+            .block(
+                Block::new()
+                    .borders(Borders::LEFT | Borders::RIGHT)
+                    .title("Data1"),
+            )
+            .data(&self.data1)
+            .style(Style::default().fg(Color::Yellow));
+        frame.render_widget(sparkline, chunks[0]);
+        let sparkline = Sparkline::default()
+            .block(
+                Block::new()
+                    .borders(Borders::LEFT | Borders::RIGHT)
+                    .title("Data2"),
+            )
+            .data(&self.data2)
+            .style(Style::default().bg(Color::Green));
+        frame.render_widget(sparkline, chunks[1]);
+        // Multiline
+        let sparkline = Sparkline::default()
+            .block(
+                Block::new()
+                    .borders(Borders::LEFT | Borders::RIGHT)
+                    .title("Data3"),
+            )
+            .data(&self.data3)
+            .style(Style::default().fg(Color::Red));
+        frame.render_widget(sparkline, chunks[2]);
+    }
 }
--- a/examples/table.rs
+++ b/examples/table.rs
@@ -1,110 +1,351 @@
-extern crate tui;
-extern crate termion;
+//! # [Ratatui] Table example
+//!
+//! The latest version of this example is available in the [examples] folder in the repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md

-use std::io;
+use color_eyre::Result;
+use itertools::Itertools;
+use ratatui::{
+    crossterm::event::{self, Event, KeyCode, KeyEventKind},
+    layout::{Constraint, Layout, Margin, Rect},
+    style::{self, Color, Modifier, Style, Stylize},
+    text::{Line, Text},
+    widgets::{
+        Block, BorderType, Cell, HighlightSpacing, Paragraph, Row, Scrollbar, ScrollbarOrientation,
+        ScrollbarState, Table, TableState,
+    },
+    DefaultTerminal, Frame,
+};
+use style::palette::tailwind;
+use unicode_width::UnicodeWidthStr;

-use termion::event;
-use termion::input::TermRead;
+const PALETTES: [tailwind::Palette; 4] = [
+    tailwind::BLUE,
+    tailwind::EMERALD,
+    tailwind::INDIGO,
+    tailwind::RED,
+];
+const INFO_TEXT: &str =
+    "(Esc) quit | (↑) move up | (↓) move down | (→) next color | (←) previous color";

-use tui::Terminal;
-use tui::backend::TermionBackend;
-use tui::widgets::{Widget, Block, border, Table};
-use tui::layout::{Group, Direction, Size};
-use tui::style::{Style, Color, Modifier};
+const ITEM_HEIGHT: usize = 4;

-struct App<'a> {
-    items: Vec<Vec<&'a str>>,
-    selected: usize,
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let app_result = App::new().run(terminal);
+    ratatui::restore();
+    app_result
+}
+struct TableColors {
+    buffer_bg: Color,
+    header_bg: Color,
+    header_fg: Color,
+    row_fg: Color,
+    selected_style_fg: Color,
+    normal_row_color: Color,
+    alt_row_color: Color,
+    footer_border_color: Color,
 }

-impl<'a> App<'a> {
-    fn new() -> App<'a> {
-        App {
-            items: vec![vec!["Row12", "Row12", "Row13"],
-                        vec!["Row21", "Row22", "Row23"],
-                        vec!["Row31", "Row32", "Row33"],
-                        vec!["Row41", "Row42", "Row43"],
-                        vec!["Row41", "Row42", "Row43"],
-                        vec!["Row41", "Row42", "Row43"]],
-            selected: 0,
+impl TableColors {
+    const fn new(color: &tailwind::Palette) -> Self {
+        Self {
+            buffer_bg: tailwind::SLATE.c950,
+            header_bg: color.c900,
+            header_fg: tailwind::SLATE.c200,
+            row_fg: tailwind::SLATE.c200,
+            selected_style_fg: color.c400,
+            normal_row_color: tailwind::SLATE.c950,
+            alt_row_color: tailwind::SLATE.c900,
+            footer_border_color: color.c400,
        }
    }
 }

-fn main() {
-    // Terminal initialization
-    let backend = TermionBackend::new().unwrap();
-    let mut terminal = Terminal::new(backend).unwrap();
+struct Data {
+    name: String,
+    address: String,
+    email: String,
+}

-
-    // App
-    let mut app = App::new();
-
-    // First draw call
-    terminal.clear().unwrap();
-    terminal.hide_cursor().unwrap();
-    draw(&mut terminal, &app);
-
-    // Input
-    let stdin = io::stdin();
-    for c in stdin.keys() {
-        let evt = c.unwrap();
-        match evt {
-            event::Key::Char('q') => {
-                break;
-            }
-            event::Key::Down => {
-                app.selected += 1;
-                if app.selected > app.items.len() - 1 {
-                    app.selected = 0;
-                }
-            }
-            event::Key::Up => {
-                if app.selected > 0 {
-                    app.selected -= 1;
-                } else {
-                    app.selected = app.items.len() - 1;
-                }
-            }
-            _ => {}
-        };
-        draw(&mut terminal, &app);
+impl Data {
+    const fn ref_array(&self) -> [&String; 3] {
+        [&self.name, &self.address, &self.email]
    }

-    terminal.show_cursor().unwrap();
+    fn name(&self) -> &str {
+        &self.name
+    }
+
+    fn address(&self) -> &str {
+        &self.address
+    }
+
+    fn email(&self) -> &str {
+        &self.email
+    }
 }

-fn draw(t: &mut Terminal<TermionBackend>, app: &App) {
+struct App {
+    state: TableState,
+    items: Vec<Data>,
+    longest_item_lens: (u16, u16, u16), // order is (name, address, email)
+    scroll_state: ScrollbarState,
+    colors: TableColors,
+    color_index: usize,
+}

-    let size = t.size().unwrap();
+impl App {
+    fn new() -> Self {
+        let data_vec = generate_fake_names();
+        Self {
+            state: TableState::default().with_selected(0),
+            longest_item_lens: constraint_len_calculator(&data_vec),
+            scroll_state: ScrollbarState::new((data_vec.len() - 1) * ITEM_HEIGHT),
+            colors: TableColors::new(&PALETTES[0]),
+            color_index: 0,
+            items: data_vec,
+        }
+    }

-    Group::default()
-        .direction(Direction::Horizontal)
-        .sizes(&[Size::Percent(100)])
-        .margin(5)
-        .render(t, &size, |t, chunks| {
-            let selected_style = Style::default().fg(Color::Yellow).modifier(Modifier::Bold);
-            let normal_style = Style::default().fg(Color::White);
-            Table::default()
-                .block(Block::default()
-                    .borders(border::ALL)
-                    .title("Table"))
-                .header(&["Header1", "Header2", "Header3"])
-                .widths(&[10, 10, 10])
-                .rows(&app.items
-                    .iter()
-                    .enumerate()
-                    .map(|(i, item)| {
-                        (item,
-                         if i == app.selected {
-                            &selected_style
-                        } else {
-                            &normal_style
-                        })
-                    })
-                    .collect::<Vec<(&Vec<&str>, &Style)>>())
-                .render(t, &chunks[0]);
+    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));
+        self.scroll_state = self.scroll_state.position(i * ITEM_HEIGHT);
+    }
+
+    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));
+        self.scroll_state = self.scroll_state.position(i * ITEM_HEIGHT);
+    }
+
+    pub fn next_color(&mut self) {
+        self.color_index = (self.color_index + 1) % PALETTES.len();
+    }
+
+    pub fn previous_color(&mut self) {
+        let count = PALETTES.len();
+        self.color_index = (self.color_index + count - 1) % count;
+    }
+
+    pub fn set_colors(&mut self) {
+        self.colors = TableColors::new(&PALETTES[self.color_index]);
+    }
+
+    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+        loop {
+            terminal.draw(|frame| self.draw(frame))?;
+
+            if let Event::Key(key) = event::read()? {
+                if key.kind == KeyEventKind::Press {
+                    match key.code {
+                        KeyCode::Char('q') | KeyCode::Esc => return Ok(()),
+                        KeyCode::Char('j') | KeyCode::Down => self.next(),
+                        KeyCode::Char('k') | KeyCode::Up => self.previous(),
+                        KeyCode::Char('l') | KeyCode::Right => self.next_color(),
+                        KeyCode::Char('h') | KeyCode::Left => self.previous_color(),
+                        _ => {}
+                    }
+                }
+            }
+        }
+    }
+
+    fn draw(&mut self, frame: &mut Frame) {
+        let vertical = &Layout::vertical([Constraint::Min(5), Constraint::Length(3)]);
+        let rects = vertical.split(frame.area());
+
+        self.set_colors();
+
+        self.render_table(frame, rects[0]);
+        self.render_scrollbar(frame, rects[0]);
+        self.render_footer(frame, rects[1]);
+    }
+
+    fn render_table(&mut self, frame: &mut Frame, area: Rect) {
+        let header_style = Style::default()
+            .fg(self.colors.header_fg)
+            .bg(self.colors.header_bg);
+        let selected_style = Style::default()
+            .add_modifier(Modifier::REVERSED)
+            .fg(self.colors.selected_style_fg);
+
+        let header = ["Name", "Address", "Email"]
+            .into_iter()
+            .map(Cell::from)
+            .collect::<Row>()
+            .style(header_style)
+            .height(1);
+        let rows = self.items.iter().enumerate().map(|(i, data)| {
+            let color = match i % 2 {
+                0 => self.colors.normal_row_color,
+                _ => self.colors.alt_row_color,
+            };
+            let item = data.ref_array();
+            item.into_iter()
+                .map(|content| Cell::from(Text::from(format!("\n{content}\n"))))
+                .collect::<Row>()
+                .style(Style::new().fg(self.colors.row_fg).bg(color))
+                .height(4)
        });
+        let bar = " █ ";
+        let t = Table::new(
+            rows,
+            [
+                // + 1 is for padding.
+                Constraint::Length(self.longest_item_lens.0 + 1),
+                Constraint::Min(self.longest_item_lens.1 + 1),
+                Constraint::Min(self.longest_item_lens.2),
+            ],
+        )
+        .header(header)
+        .highlight_style(selected_style)
+        .highlight_symbol(Text::from(vec![
+            "".into(),
+            bar.into(),
+            bar.into(),
+            "".into(),
+        ]))
+        .bg(self.colors.buffer_bg)
+        .highlight_spacing(HighlightSpacing::Always);
+        frame.render_stateful_widget(t, area, &mut self.state);
+    }

-    t.draw().unwrap();
+    fn render_scrollbar(&mut self, frame: &mut Frame, area: Rect) {
+        frame.render_stateful_widget(
+            Scrollbar::default()
+                .orientation(ScrollbarOrientation::VerticalRight)
+                .begin_symbol(None)
+                .end_symbol(None),
+            area.inner(Margin {
+                vertical: 1,
+                horizontal: 1,
+            }),
+            &mut self.scroll_state,
+        );
+    }
+
+    fn render_footer(&self, frame: &mut Frame, area: Rect) {
+        let info_footer = Paragraph::new(Line::from(INFO_TEXT))
+            .style(
+                Style::new()
+                    .fg(self.colors.row_fg)
+                    .bg(self.colors.buffer_bg),
+            )
+            .centered()
+            .block(
+                Block::bordered()
+                    .border_type(BorderType::Double)
+                    .border_style(Style::new().fg(self.colors.footer_border_color)),
+            );
+        frame.render_widget(info_footer, area);
+    }
+}
+
+fn generate_fake_names() -> Vec<Data> {
+    use fakeit::{address, contact, name};
+
+    (0..20)
+        .map(|_| {
+            let name = name::full();
+            let address = format!(
+                "{}\n{}, {} {}",
+                address::street(),
+                address::city(),
+                address::state(),
+                address::zip()
+            );
+            let email = contact::email();
+
+            Data {
+                name,
+                address,
+                email,
+            }
+        })
+        .sorted_by(|a, b| a.name.cmp(&b.name))
+        .collect_vec()
+}
+
+fn constraint_len_calculator(items: &[Data]) -> (u16, u16, u16) {
+    let name_len = items
+        .iter()
+        .map(Data::name)
+        .map(UnicodeWidthStr::width)
+        .max()
+        .unwrap_or(0);
+    let address_len = items
+        .iter()
+        .map(Data::address)
+        .flat_map(str::lines)
+        .map(UnicodeWidthStr::width)
+        .max()
+        .unwrap_or(0);
+    let email_len = items
+        .iter()
+        .map(Data::email)
+        .map(UnicodeWidthStr::width)
+        .max()
+        .unwrap_or(0);
+
+    #[allow(clippy::cast_possible_truncation)]
+    (name_len as u16, address_len as u16, email_len as u16)
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::Data;
+
+    #[test]
+    fn constraint_len_calculator() {
+        let test_data = vec![
+            Data {
+                name: "Emirhan Tala".to_string(),
+                address: "Cambridgelaan 6XX\n3584 XX Utrecht".to_string(),
+                email: "tala.emirhan@gmail.com".to_string(),
+            },
+            Data {
+                name: "thistextis26characterslong".to_string(),
+                address: "this line is 31 characters long\nbottom line is 33 characters long"
+                    .to_string(),
+                email: "thisemailis40caharacterslong@ratatui.com".to_string(),
+            },
+        ];
+        let (longest_name_len, longest_address_len, longest_email_len) =
+            crate::constraint_len_calculator(&test_data);
+
+        assert_eq!(26, longest_name_len);
+        assert_eq!(33, longest_address_len);
+        assert_eq!(40, longest_email_len);
+    }
 }
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				`<!-- Please read CONTRIBUTING.md before submitting any pull request. -->`