ratatui-macros

We are excited to announce the new version of ratatui - a Rust library that's all about cooking up TUIs 👨‍🍳🐀

✨ Release highlights: https://ratatui.rs/highlights/v0302/

⚠️ List of breaking changes can be found here.

Features

• 90639c1 (uncategorized) Add Termina backend by @joshka in #2561

  Summary

  • add the ratatui-termina backend crate using the published termina
    crate
  • expose the backend through the termina feature and Ratatui
    prelude/backend re-exports
  • add a small Termina event-loop example and wire the backend into CI,
    xtask, README generation, and docs

  Refs #1784

  Validation

  • cargo +nightly fmt
  • cargo check -p ratatui-termina --all-features --all-targets
  • cargo check -p ratatui --no-default-features --features termina
  • cargo check -p xtask
  • cargo check -p release-header
  • cargo xtask check-backend termina
  • cargo xtask test-backend termina
  • cargo xtask rdme --check
  • markdownlint-cli2 ARCHITECTURE.md ratatui-termina/README.md .github/ISSUE_TEMPLATE/bug_report.md

  ---

Bug Fixes

• fce3c80 (widgets) Require thread-safe shadow effects by @joshka in #2584

  Summary

  • require custom shadow effects to preserve the auto traits expected by
    Block-backed widgets
  • document the CellEffect auto-trait contract
  • add a public widget regression test for the affected ratatui::widgets
    re-exports

  Fixes #2583

  ---

• e306ce6 (buffer) Create updates for "uncovered" cells by @benjajaja in #2587

  When a wide cell from the previous buffer is replaced by a short/normal
  cell, the trailing cell does not get an update if its content does not
  change. But if the wide cell has a background (or other) style, the
  terminal did render the trailing cell with that style.

  Force trailing cells to update if background, underline, or modifiers
  are different than the wide cell. We can ignore foreground.

  Fixes #2585 (see that for the detailed visual reports)

• 81e667f (scrollbar) Keep a large thumb within the track at the end by @satyakwok in #2594

  Closes #2582.

  Problem

  When the content is shorter than the viewport, the thumb is large
  relative to the track. With the position at the end, part_lengths
  clamped thumb_start to track_length - 1 while thumb_length was
  clamped independently to [1, track_length], so thumb_start + thumb_length could exceed track_length.

  bar_symbols lays out begin + track_start + thumb + track_end + end
  and zips it against the cells of the area. When the thumb overruns the
  track, track_end saturates to 0 but the thumb still emits more cells
  than the track can hold, so the trailing end symbol is pushed past the
  end of the area. The last visible cell ends up being a thumb (█) where
  the end arrow (▼) should be.

  Concretely, for the issue's repro (VerticalRight, content_length = 9, position = 8, height 24): track is 22, thumb_length = 17,
  thumb_start = 6, and 6 + 17 = 23 > 22.

  This is a regression from v0.30.0, where thumb_length was derived as
  thumb_end - thumb_start and therefore always fit within the track.

  Fix

  Clamp thumb_start to track_length - thumb_length (instead of
  track_length - 1) so the thumb always fits within the track and the
  end symbol is preserved.

  Test

  Two regression tests, both fail on main and pass with the fix:

  • thumb_stays_within_track_for_large_thumb_at_end checks
    part_lengths directly with the issue's parameters — asserts
    thumb_start + thumb_length <= track_length and that the parts sum to
    the track length.
  • render_scrollbar_keeps_end_symbol_for_large_thumb renders the #2582
    case (both arrows, large thumb at the end) and asserts the end symbol is
    drawn rather than overwritten by a thumb cell.

  All existing scrollbar tests still pass.

Miscellaneous Tasks

• c75d778 (ci) Add cargo-udeps dependency check by @joshka in #2599

  Adds cargo xtask udeps and runs it from CI as a required job.

  This complements cargo-machete rather than replacing it. cargo-machete
  is a fast static source scan, which is why it missed the package-level
  unused deps fixed in #2598 when the same dependency names were still
  referenced by example crates. cargo-udeps compiles the workspace and
  checks rustc dep-info, so it can catch unused dependency declarations
  for the package being checked.

  To make the new job pass, this also removes the remaining true-positive
  unused dev-deps and records explicit cargo-udeps ignores for current
  false positives / intentional cases: ratatui-core critical-section,
  ratatui-crossterm's duplicate crossterm version feature shape, and
  ratatui-termwiz's doc-example-only ratatui dev-dependency.

  I searched existing issues and PRs for udeps / cargo-udeps / "cargo
  udeps". I did not find prior ratatui discussion about adopting
  cargo-udeps; the only hits were Dependabot PR bodies for
  taiki-e/install-action release notes mentioning cargo-udeps version
  updates, for example #1971, #2095, #2194, and #2522.

  Validation:- cargo xtask udeps

  • cargo xtask format --check

  ---

• 4a63d41 (uncategorized) Remove unused dependencies by @KikiKian in #2598

  Audit removes these dependencies that are not used:

  ratatui/Cargo.toml — Removed from [dev-dependencies]:

  • futures
  • rand_chacha
  • tokio
  • tracing
  • tracing-appender
  • tracing-subscriber

  ratatui-core/Cargo.toml — Moved from [dependencies] →
  [dev-dependencies]:

  • indoc

  ---

Continuous Integration

• 36854ef (uncategorized) Add auto-merge required gate by @joshka in #2596

  Summary

  This makes GitHub auto-merge usable for Ratatui PRs once maintainers are
  happy with the change but CI is still running.

  The workflow change adds a single aggregate required job to the main
  CI workflow. The repository now has auto-merge
  enabled
  and an ensure checks pass
  ruleset
  that requires that required status context on main.

  Why

  Without a required status context, GitHub's auto-merge button is not
  useful for the maintainer flow we want. The goal is to let a maintainer
  review a PR, decide it is ready, click auto-merge, and move on without
  coming back later just to check whether the remaining jobs finished.

  This does not relax the merge policy. GitHub's own auto-merge behavior
  is to merge only after all required reviews and required status checks
  are satisfied. This change gives GitHub a stable required status to wait
  on automatically.

  Precedent

  I have been using this same auto-merge pattern in
  ratatui/tui-widgets, where
  it has worked well for the intended maintainer flow: once a PR looks
  ready, I can enable auto-merge and let GitHub merge it after the
  remaining checks and review requirements are satisfied.

  How it works

  The new required job depends on the main CI jobs in
  .github/workflows/ci.yml and always runs after them. It fails if any
  required dependency fails, is cancelled, or is skipped.

  The repository ruleset requires only this aggregate required context
  instead of requiring every individual matrix job separately. That gives
  GitHub one stable status to wait on while preserving the existing CI
  coverage.

  Things to know

  • Auto-merge is opt-in per PR. Maintainers still choose when to click
    it.
  • It does not skip review requirements, status checks, labels, or any
    other protection rule.
  • A PR with auto-merge enabled can still show as blocked while checks or
    required reviews are pending. That is expected.
  • If something needs to merge normally, maintainers can still use the
    regular merge path or an allowed ruleset bypass. This is a convenience
    path, not a hard blocker.
  • Existing open PRs may need a rebase or synchronize event after this
    lands so they pick up the new required workflow job.
  • If a new required CI job is added later, it should be added to the
    required.needs list or it will not be represented by the aggregate
    gate.
  • Jobs that are intentionally allowed to fail should be handled
    carefully before adding them to required.needs, because skipped,
    cancelled, and failed dependencies make the aggregate fail.

  Current PR state

  Auto-merge is already enabled on this PR. If you approve it and the
  required checks pass, GitHub will squash-merge it automatically;
  approving it is enough to let the PR merge once the remaining
  requirements are satisfied.

  GitHub docs

  • Automatically merging a pull
    request
  • Managing auto-merge for pull requests in your
    repository
  • About
    rulesets
  • Require status checks to pass before
    merging
  • About status
    checks
  • Troubleshooting required status
    checks

  Validation

  • ruby -e 'require "yaml"; YAML.load_file(".github/workflows/ci.yml"); puts "ok"'
  • actionlint .github/workflows/ci.yml
  • Verified ratatui/ratatui has allow_auto_merge: true
  • Verified the active ensure checks pass ruleset requires status
    context required
  • Verified this PR has squash auto-merge enabled and is blocked pending
    checks/review

New Contributors

• @satyakwok made their first contribution in #2594
• @KikiKian made their first contribution in #2598

Full Changelog: ratatui-v0.30.1...ratatui-v0.30.2

Breaking Changes

• Use Constraint instead of integers to specify the widths of the Table widget's columns. This will allow more responsive tables.

Table::new(header, row)
  .widths(&[15, 15, 10])
  .render(f, chunk);

becomes:

Table::new(header, row)
  .widths(&[
    Constraint::Length(15),
    Constraint::Length(15),
    Constraint::Length(10),
  ])
  .render(f, chunk);

• Bump crossterm to 0.13.
• Use Github Actions for CI (Travis and Azure Pipelines integrations have been deleted).

Features

• Add support for horizontal and vertical margins in Layout.

Breaking Changes

• Update crossterm backend

Other

• (deps) bump the cargo-dependencies group with 2 updates (#73)
• (deps) bump ratatui from 0.28.0 to 0.28.1 in the cargo-dependencies group (#70)

Features

• Add a new curses backend (with Windows support thanks to pancurses).
• Add Backend::get_cursor and Backend::set_cursor methods to query and set the position of the cursor.
• Add more constructors to the Crossterm backend.
• Add a demo for all backends using a shared UI and application state.
• Add Ratio as a new variant of layout Constraint. It can be used to define exact ratios constraints.

Breaking Changes

• Add support for multiple modifiers on the same Style by changing Modifier from an enum to a bitflags struct.

So instead of writing:

let style = Style::default().add_modifier(Modifier::Italic);

one should use:

let style = Style::default().add_modifier(Modifier::ITALIC);
// or
let style = Style::default().add_modifier(Modifier::ITALIC | Modifier::BOLD);

Bug Fixes

• Ensure correct behavior of the alternate screens with the Crossterm backend.
• Fix out of bounds panic when two Buffer are merged.

🐛 Bug Fixes

• Bump version to 0.5.0

Other

• (deps) bump ratatui to 0.28.0 (#66)
• (deps) bump trybuild from 1.0.98 to 1.0.99 in the cargo-dependencies group (#65)
• (deps) bump trybuild from 1.0.97 to 1.0.98 in the cargo-dependencies group (#62)

Added

• allow span macro to accept a bare expression (#61)

Other

• (deps) bump trybuild from 1.0.96 to 1.0.97 in the cargo-dependencies group (#59)

Added

• Use ::ratatui instead of ratatui (#54)
• Add row! macro (#52)

Other

• Update README with row! documentation (#56)
• Make doc examples shorter by removing duplicate imports (#55)

Other

• (deps) bump ratatui from 0.26.3 to 0.27.0 in the cargo-dependencies group (#51)
• Update dependabot.yml to group dependencies (#50)
• (deps) bump ratatui from 0.26.2 to 0.26.3 (#48)
• (deps) bump trybuild from 1.0.95 to 1.0.96 (#47)

Features

• Add a new canvas shape: Rectangle.
• Official support of Crossterm backend.
• Make it possible to choose the divider between Tabs.
• Add word wrapping on Paragraph.
• The gauge widget accepts a ratio (f64 between 0 and 1) in addition of a percentage.

Breaking Changes

• Upgrade to Rust 2018 edition.

Bug Fixes

• Fix rendering of double-width characters.
• Fix race condition on the size of the terminal and expose a size that is safe to use when drawing through Frame::size.
• Prevent unsigned int overflow on large screens.

Added

• (layout) [breaking] Use *= instead of =* (#45)

Added

• Better error messages for span! macro (#43)

Fixed

• downgrade ratatui to 0.26.2 (#41)

Other

• Update authors to ratatui developers (#44)

Features

• Add experimental test backend

Added

• Use release-plz (#38)
• Add text! macro (#36)
• Add fill constraint (#34)
• [breaking] Remove color palette! macro (#32)
• Replace raw! and styled! with span! macro (#30)
• Add line! attribute macro (#29)
• (text) add raw! and styled! macros (#4)

Fixed

• Update repo url in Cargo.toml (#39)

Other

• Use .areas(area) instead of .split(area).to_vec().try_into().unwrap() (#37)
• Update README.md with short description of span and line macros (#33)
• format using cargo +nightly fmt (#31)
• (deps) bump ratatui from 0.27.0-alpha.3 to 0.27.0-alpha.5 (#27)
• (deps) bump trybuild from 1.0.91 to 1.0.93 (#28)
• (deps) bump ratatui from 0.27.0-alpha.2 to 0.27.0-alpha.3 (#24)
• (deps) bump trybuild from 1.0.90 to 1.0.91 (#23)
• (deps) bump trybuild from 1.0.88 to 1.0.90 (#20)
• (deps) bump ratatui from 0.27.0-alpha.0 to 0.27.0-alpha.2 (#22)
• (deps) bump mio from 0.8.10 to 0.8.11 (#18)
• (deps) bump ratatui from 0.26.0-alpha.1 to 0.27.0-alpha.0 (#19)
• add cargo husky pre-commit hook (#8)
• Create dependabot.yml (#7)
• use rust cache to cache deps (#6)
• readme tweaks (#5)
• Update README.md
• Update README.md
• Update README.md
• Update README.md
• Add link to ratatui

Features

• Add start_corner option for List
• Add more text alignment options for Paragraph

Features

• Terminal implements Debug

Breaking Changes

• Use FnOnce instead of FnMut in Group::render

Features

• Add AlternateScreenBackend in termion backend
• Add TermionBackend::with_stdout in order to let an user of the library provides its own termion struct
• Add tests and documentation for Buffer::pos_of
• Remove leading whitespaces when wrapping text

Bug Fixes

• Fix debug_assert in Buffer::pos_of
• Pass the style of SelectableList to the underlying List
• Fix missing character when wrapping text
• Fix panic when specifying layout constraints

Features

• Add MouseBackend in termion backend to handle scroll and mouse events
• Add generic Item for items in a List
• Drop log4rs as a dev-dependencies in favor of stderrlog

Breaking Changes

• Rename TermionBackend to RawBackend (to distinguish it from the MouseBackend)
• Generic parameters for List to allow passing iterators as items
• Generic parameters for Table to allow using iterators as rows and header
• Generic parameters for Tabs
• Rename border bitflags to Borders