Unclaimed project

Are you a maintainer of ratatui? Claim this project to take control of your public changelog and roadmap.

Changelog

ratatui

A Rust crate for cooking up terminal user interfaces (TUIs) 👨‍🍳🐀 https://ratatui.rs

ratatui/ratatui

Related Projects

mapbox-navigation-android

Mapbox Navigation SDK for Android

ToastFish

一个利用摸鱼时间背单词的软件。

barcodelib

C# Barcode Image Generation Library

haze

Background blurring for Compose Multiplatform / Jetpack Compose

View all projects →

ratatui-termwiz-v0.1.0 - ratatui Release Notes | AnnounceHQ

Direction::perpendicular(self)

56d5e05 (bar) Update label and text_value to accept Into<> by @Emivvvvv in #1471 [breaking]

BREAKING CHANGE:label and text_value now accept Into<> types, which breaks type inference.
- Bar::default().label("foo".into());
+ Bar::default().label("foo");
- Bar::default().text_value("bar".into());
+ Bar::default().text_value("bar");

ff729b7 (scrollbar) Support retrieving the current position of state by @orhun in #1552

As of now it is possible to change the position of the Scrollbar but not possible to retrieve the position for further use. e.g.
let mut state = ScrollbarState::default();
state.next();
This commit adds a new method "current_position" (since position is already taken by the fluent setter) for that purpose:
let index = state.get_position(); // yay
See #1545 for the concrete usage of this.

03f3f6d (style) Allow add/sub modifiers to be omitted in Style serialization. by @rcorre in #2057

It's really useful that Style supports Deserialize, this allows TUI apps to have configurable theming without much extra code.

However, deserializing a style currently fails if add_modifier and sub_modifier are not specified. That means the following TOML config:
[theme.highlight]
fg = "white"
bg = "black"
Will fail to deserialize with "missing field add_modifier". It should be possible to omit modifiers and have them default to "none".

4c301e8 (text) Implement AddAssign for Text by @acuteenvy in #1956

This makes it possible to add a second Text instance to a first one using the += operator.
let mut text = Text::from("line 1");
text += Text::from("line 2");
Style and alignment applied to the second text is ignored (though styles and alignment of lines and spans are copied).

96d097e (uncategorized) Implement Rect ops for moving by @joshka in #1596

feat:implement Rect ops for moving

Implemented Add, AddAssign, Sub, and SubAssign on Rect for Offset. This makes it possible to move rects
let rect = Rect::new(1, 2, 3, 4);
let moved = rect + Offset(1, 2);
let moved = rect - Offset(1, 2);
let moved = rect + Offset(-1, -2);
Additionally Rect, Size, Offset, and Position now all have MIN and MAX consts.

6dcd53b (uncategorized) Add ergonomic methods for layouting Rects by @joshka in #1909

This commit introduces new methods for the Rect struct that simplify the process of splitting a Rect into sub-rects according to a given Layout. By putting these methods on the Rect struct, we make it a bit more natural that a layout is applied to the Rect itself, rather than passing a Rect to the Layout struct to be split.

Adds:- Rect::layout and Rect::try_layout methods that allow splitting a Rect into an array of sub-rects according to a given Layout.

Rect::layout_vec method that returns a Vec of sub-rects.

Layout::try_areas method that returns an array of sub-rects, with compile-time checks for the number of constraints. This is added mainly for consistency with the new Rect methods.
use ratatui_core::layout::{Layout, Constraint, Rect};
let area = Rect::new(0, 0, 10, 10);
let layout = Layout::vertical([Constraint::Fill(1); 2]);

// Rect::layout() infers the number of constraints at compile time:
let [top, main] = area.layout(&layout);

// Rect::try_layout() and Layout::try_areas() do the same, but return a
// Result:
let [top, main] = area.try_layout(&layout)?;
let [top, main] = layout.try_areas(area)?;

// Rect::layout_vec() returns a Vec of sub-rects:
let areas_vec = area.layout_vec(&layout);

// you can also explicitly specify the number of constraints:
let areas = area.layout::<2>(&layout);
let areas = area.try_layout::<2>(&layout)?;
let areas = layout.try_areas::<2>(area)?;

7bc78bc (uncategorized) Add ratatui::run() method by @joshka in #1707

This introduces a new ratatui::run() method which runs a closure with a terminal initialized with reasonable defaults for most applications. This calls ratatui::init() before running the closure and ratatui::restore() after the closure completes, and returns the result of the closure.

A minimal hello world example using the new ratatui::run() method:
fn main() -> Result<(), Box<dyn std::error::Error>> {
    ratatui::run(|terminal| {
        loop {
            terminal.draw(|frame| frame.render_widget("Hello World!", frame.area()))?;
            if crossterm::event::read()?.is_key_press() {
                break Ok(());
            }
        }
    })
}
Of course, this also works both with apps that use free methods and structs:
fn run(terminal: &mut DefaultTerminal) -> Result<(), AppError> { ... }

ratatui::run(run)?;
struct App { ... }

impl App {
    fn new() -> Self { ... }
    fn run(mut self, terminal: &mut DefaultTerminal) -> Result<(), AppError> { ... }
}

ratatui::run(|terminal| App::new().run(terminal))?;

671c2b4 (uncategorized) Support merging the borders of blocks by @j-g00da

When two borders overlap, they will automatically merge into a single, clean border instead of overlapping.

This improves visual clarity and reduces rendering glitches around corners.

For example:
assert_eq!(Cell::new("┘").merge_symbol("┏", MergeStrategy::Exact).symbol(), "╆");

702fff5 (uncategorized) Implement stylize methods directly on Style by @joshka in #1572 [breaking]

This makes it possible to create constants using the shorthand methods.
const MY_STYLE: Style = Style::new().blue().on_black();
Rather than implementing Styled for Style and then adding extension methods that implement the Stylize shorthands, this implements the methods as const functions directly on Style.

BREAKING CHANGE:Style no longer implements Styled. Any calls to methods implemented by the blanket implementation of Stylize are now defined directly on Style. Remove the Stylize import if it is no longer used by your code.

The reset() method does not have a direct replacement, as it clashes with the existing reset() method. Use Style::reset() rather than some_style.reset()

Fixes:#1158

fcb47d6 (uncategorized) Rename Alignment to HorizontalAlignment and add VerticalAlignment by @joshka in #1735 [breaking]

We don't anticipate removing or deprecating the type alias in the near future, but it is recommended to update your imports to use the new name.

Added a VerticalAlignment enum to make the API more consistent. We don't have a specific use case for it yet, but it's better to add it now and be able to use it in the future.

BREAKING-CHANGE:The Alignment enum has been renamed to HorizontalAlignment to better reflect its purpose. A type alias has been added to maintain backwards compatibility, however there are some cases where type aliases are not enough to maintain backwards compatibility. E.g. when using glob imports to import all the enum variants. This should not affect most users, but it is recommended to update your imports to use the new name.
- use ratatui::layout::Alignment;
+ use ratatui::layout::HorizontalAlignment;

- use Alignment::*;
+ use HorizontalAlignment::*;

2714d6b (uncategorized) Add array and tuple RGB color conversion methods by @joshka in #1703

Other crates (e.g. colorgrad) that deal with colors can convert colors to a tuple of 3 or 4 u8 values. This commit adds conversion methods from these types to a Color::Rgb instance. Any alpha value is ignored.
Color::from([255, 0, 0]);
Color::from((255, 0, 0));
Color::from([255, 0, 0, 255]);
Color::from((255, 0, 0, 255));

50ba965 (uncategorized) Add a new RatatuiMascot widget by @Its-Just-Nans in #1584

Move the Mascot from Demo2 into a new widget. Make the Rat grey and adjust the other colors.
frame.render_widget(RatatuiMascot::default(), frame.area());

a89d3d6 (buffer) Clear behavior with VS16 wide emojis by @nornagon in #2063
This fixes a bug where certain emojis like ⌨️ would sometimes be "overlaid" onto existing content from the buffer, instead of properly clearing.

example demonstrating bug

This PR was generated by Codex, and validated by me:
1. Behavior of the above example code was buggy before this fix (showed overlaying "b" on top of the keyboard emoji), and fixed after.
2. The U+FE0F check is not strictly required, but I did note that emoji without this char don't exhibit the buggy behavior, even without the fix.
ec30390 (canvas) Round coordinates to nearest grid cell by @joshka in #1507

Previously the canvas coordinates were rounded towards zero, which causes the rendering to be off by one pixel in some cases. It also meant that pixels at the extreme edges of the canvas can only be drawn if the point was exactly on the edge of the canvas. This commit rounds the coordinates to the nearest integer instead. This may change the output for some apps using Canvas / Charts.
afd1ce1 (canvas) Lines that start outside the visible grid are now drawn by @renesat in #1501

Previously lines with points that were outside the canvas bounds were not drawn at all. Now they are clipped to the bounds of the canvas so that the portion of the line within the canvas is draw.

To facilitate this, a new Painter::bounds() method which returns the bounds of the canvas is added.

Fixes:https://github.com/ratatui/ratatui/issues/1489
2b0a044 (ci) Add contents write permission to release-plz PR by @marcoieni in #2119

https://release-plz.dev/docs/github/quickstart#3-setup-the-workflow

Fixes https://github.com/release-plz/release-plz/issues/2439
18e70d3 (crossterm) Terminal should keep Bold when removing Dim by @MarSik in #1541

The Dim removal should behave the same as the logic for Bold removal that sends NormalIntensity sequence and then restores Dim when needed.
16b76e3 (demo) Update the width of demo2 tape by @orhun in #2164

fixes #1721
dca331c (demo) Support tab key in demo2 example by @orhun in #1726

see #1721

Not sure what caused this - it's been there for a while probably and we didn't realize it since we used demo2-destroy mostly.
0fd4753 (examples) Run the correct example for chart by @orhun in #1679

fixes #1678
39479e2 (examples) Ensure that example projects are not published by @orhun in #1672
9314312 (layout) Feature flag cache related types by @joshka in #1842
2dd1977 (layout-cache) Import NonZeroUsize only when layout-cache is enabled by @j-g00da in #1839

This silences unused import warning, when layout-cache is disabled.
564a9d7 (line-gauge) Pad default label to display 3 numbers by @martinetd in #2053

Display the default label of the LineGauge widget padded to fill 3 cells. This makes it so that the label doesn't shift around when going from a single digit to double / triple digits.

To maintain the existing behavior, use a custom label by calling .label() on the LineGauge.
a692a6e (lint) Apply rust 1.84 clippy suggestions by @joshka in #1612

The canvas map constants are now statics instead. Fixes https://rust-lang.github.io/rust-clippy/master/index.html#large_const_arrays
2e54d5e (macros) Use $crate re-export in text macro by @airblast-dev in #1832
79d5165 (no_std) Propagate std feature flag to dependencies by @j-g00da in #1838

Disables std feature flags in dependencies and only enables them with ratatui and ratatui-core's std feature flag. This partially fixes the issue of still depending on std, when std feature flag is disabled.
00da8c6 (no_std) Provide f64 polyfills for no_std compatibility by @j-g00da in #1840

Related:https://github.com/rust-lang/rust/issues/137578
3b13240 (scrollbar) Check for area.is_empty() before rendering by @farmeroy in #1529

This adds the area.is_empty() back into the scrollbar render method. Without it, the widget panics if the height is 0.
f57b696 (span) Dont render control characters by @EdJoPaTo in #1312
2ce958e (table) Allow display of additional table row, if row height > 1 by @Lunderberg in #1452
0a25bc1 (tests) Update the stderr snapshot for ratatui-macros by @orhun in #2161

New 🦀 broke the CI
5fa342c (widgets) Fix centered block title truncation by @ognis1205 in #1973

Previously block titles that were aligned center were truncated poorly (aligned to the left, and the last non-fitting title would be truncated on the left and right. This now truncates the titles more obviously centered.
f919b25 (uncategorized) String_to_string lint is now part of implicit_clone by @joshka in #2173
1fe64de (uncategorized) Include underline color in anstyle conversion by @aschey in #2004

Underline color wasn't included in the style conversion logic.
c1b8528 (uncategorized) Panic when rendering widgets on too small buffer by @j-g00da in #1996

Fixes panic on overflow on horizontal Barchart and RatatuiMascot and adds proper tests to all widgets.
08b21fa (uncategorized) Fix panic when rendering a Paragraph out of bounds by @jwodder in #1670

Fixes #1667.
80bc818 (uncategorized) Fix truncation of left aligned block titles by @joshka in #1931

truncate the right side of left aligned titles rather than the left side of right aligned titles. This is more obvious as the left side of text often contains more important information. And we generally read left to right.

This change makes centered titles overwrite left aligned titles and right aligned titles overwrite centered or left aligned titles.

Fixes:https://github.com/ratatui/ratatui/issues/358
21e3b59 (uncategorized) Fix handling of multi-byte chars in bar chart by @joshka in #1934

The split_at method requires that the split point is at a valid utf8 character boundary.

Fixes:https://github.com/ratatui/ratatui/issues/1928
e1e4004 (uncategorized) Derive copy for list state by @janTatesa in #1921
12cb5a2 (uncategorized) Allow canvas area to exceed u16::MAX by @Daksh14 in #1891

This allows Canvas grids where the width * height exceeds u16::MAX by converting values to usize earlier in several methods.

Fixes:https://github.com/ratatui/ratatui/issues/1449
09cc9ef (uncategorized) Typo in changelog by @joshka in #1857
c238aca (uncategorized) padding_right() should set right padding instead of left by @sxyazi in #1837

Fixes https://github.com/ratatui/ratatui/issues/1836
c90ba97 (uncategorized) Avoid unnecessary imports in minimal build by @cgzones in #1787

core::ops::Range is only used with the feature scrolling-regions. Ensure a minimal cargo check reports no warnings.
416ebdf (uncategorized) Correct clippy errors introduced by rust 1.86.0 update by @j-g00da in #1755

New version of rust (1.86.0) caused CI to fail.
4eac5b2 (uncategorized) Make deprecation notes more helpful by @joshka in #1702

AI coding assistants use the deprecation notes to automatically suggest fixes. This commit updates the deprecation notes to push those tools to suggest the correct replacement methods and types.

Specifically, AI tools often suggest using Buffer::get(x, y), because of their training data where this was prevalent. When fixing these deprecations, they often incorrectly suggest using Buffer::get(x, y) instead of Buffer[(x, y)].
35a8642 (uncategorized) Rect::positions() should be empty when width is 0 and height is nonzero by @jwodder in #1669

Fixes #1666.
f5fc819 (uncategorized) Avoid extra line break on whitespace only lines when wrapping paragraphs by @dotdash in #1636

Currently whitespace only lines produces an extra line break when trimming is disabled, because both the trimmed as well as the non-trimmed line get inserted. Fix this by only inserting the non-trimmed one.
2892bdd (uncategorized) Rust 1.83 clippy lints by @joshka in #1527

https://rust-lang.github.io/rust-clippy/master/index.html#needless_lifetimes
36e2d1b (uncategorized) Add feature(doc_cfg) when generating docs by @joshka in #1506
4d7704f (uncategorized) Make StatefulWidget and Ref work with unsized State by @thscharler in #1505

StatefulWidget::State and StatefulWidgetRef::State are now ?Sized.

This allows implementations of the traits to use unsized types for the State associated type. This is turn is useful when doing things like boxing different stateful widget types with State which implements Any, are slices or any other dynamically sized type.
7b87509 (uncategorized) Typo by @marcoieni in #1480

40e96a2 (block) Add collapsed border example by @joshka in #1899
d291042 (block) Revise the block example by @orhun in #1520
- Moves the block example from ratatui to ratatui-widgets
- Simplifies the example (bordered, styled, custom borders)
see #1512
0951da5 (breaking-changes) Improve migration guide for Backend::Error by @j-g00da in #1908

Related:https://github.com/fujiapple852/trippy/pull/1588
bbe1cf9 (breaking-changes) Change MSRV to 1.85 by @j-g00da in #1896

The minimum supported Rust version is now for ratatui v0.30 is 1.85
c7912f3 (breaking-changes) Fix header level by @j-g00da in #1825
fcde9cb (changelog) Fix typo by @orhun in #1463
73488ab (contributing) Fix link to widgets_block_renders test by @ognis1205 in #2101

The CONTRIBUTING.md referenced tests/widgets_block.rs, but the correct path is ratatui/tests/widgets_block.rs. Updated the link so that readers can navigate to the test example without 404 error.
0b025db (contributing) Fix grammar by @j-g00da in #1958
1197b2a (contributing) Add note about using nightly for formatting by @joshka in #1816
3ae6bf1 (contributing) Use cargo-xtask for instructions by @orhun in #1509
- Updates CONTRIBUTING.md about the usage of xtask
- Removes Makefile.toml
22e3e84 (core) Remove link to Paragraph widget by @orhun in #1683
b65788c (examples) Remove duplicated link by @matthiasbeyer in #2212
200b217 (examples) Add VHS tapes and docs for widget examples by @orhun in #2114

fixes #1982

Later on I'll figure out an easy way to regenerate this in the CI and possibly do the same for the app examples' VHS tapes. That's why I haven't added a script or mentioned anything in the docs yet (hint: #1721)
861fbdf (examples) Fix a typo by @j-g00da in #1890

Makes CI typos check pass again
882cc3c (examples) Update app examples with tapes by @orhun in #1673
4393fae (examples) Move scrollbar example to examples folder by @orhun in #1665
9ea70e2 (examples) Move widget-impl example to examples folder by @orhun in #1663
774ab78 (examples) Move widget-ref-container example to examples folder by @orhun in #1664

see #1512
910d16e (examples) Move user-input example to examples folder by @orhun in #1659
dbfb7da (examples) Move table example to examples folder by @orhun in #1657
cb2a58a (examples) Move tracing example to examples folder by @orhun in #1658
7e00b64 (examples) Move panic example to examples folder by @orhun in #1655
8127590 (examples) Move modifiers example to examples folder by @orhun in #1654
7c40c0b (examples) Move popup example to examples folder by @orhun in #1656

see #1512
d87354f (examples) Move list example to examples folder by @orhun in #1653

see #1512

also renames it to todo-list
621226f (examples) Move inline example to examples folder by @orhun in #1651
9ba7d25 (examples) Move hyperlink example to examples folder by @orhun in #1650
bb94d1c (examples) Move minimal example to examples folder by @orhun in #1649
9f399ac (examples) Move gauge example to examples folder by @orhun in #1646
104d6a6 (examples) Move custom-widget example to examples folder by @orhun in #1644
fa8ca01 (examples) Move flex example to examples folder by @orhun in #1642
f5fde0e (examples) Move constraints example to examples folder by @orhun in #1641
fc70288 (examples) Move constraint-explorer example to examples folder by @orhun in #1640
325f961 (examples) Move hello-world example to examples folder by @orhun in #1647
867c4bc (examples) Move colors-rgb example to examples folder by @joshka in #1582
- docs: move colors-rgb example to examples folder
- docs: update main examples README
72334ed (layout) Update documentation to point to kasuari solver by @a-kenji in #2003
2be9ccb (layout) Remove unnecessary path prefix by @j-g00da in #1766
b669ceb (layout) Change cassowary to kasuari crate reference by @j-g00da in #1765
f907c74 (license) Update copyright years by @LVivona in #1639

Update MIT Licence to copyright year 2025
68b9f67 (readme) Add Built with Ratatui badge for downstream projects by @harilvfs in #1905
088aac1 (readme) Tweak links and badges by @joshka in #1598
6e43672 (readme) Reimagine README.md by @orhun in #1569

This is the result of the re-imagination of a more suitable README.md. It is simpler and shorter: not giving more information to the user than they actually need.

Also updates the quickstart code with the up-to-date version and adds link to templates which was missing.
8f28247 (readme) Correct examples links by @HoKim98 in #1484
9f90f74 (readme) Fix broken link by @nilsmartel in #1485
260af68 (readme) Include iocraft as an alternative by @kdheepak in #1483
8e5151f (rect) Fix typo in the Rect::outer function comments by @orhun in #2123
40f13c6 (rect) Update the outdated comment for Rect::area() by @isgin01 in #2100

The return value of Rect.area() is no longer of u16 type, and the value is not being clumped anymore.
ce16692 (release) Fix typo by @j-g00da in #1754
9a930a6 (terminal) Made usage of Terminal::get_frame() clearer by @Blaeriz in #2071

Closes : https://github.com/ratatui/ratatui/issues/1200
b08b4cb (terminal) Add disclaimer about panics to Terminal::new by @lolbinarycat in #2088

part of #2087

cc @orhun
dafb716 (widgets) Add example for grouped barchart by @orhun in #1566

related #1512
ed5dd73 (widgets) Add example for tabs by @orhun in #1559

related #1512

Also removes the tabs example from ratatui crate since it overlaps with this new example in terms of functionality and it was not following the general theme of other examples.
fab5321 (widgets) Add example for scrollbar by @orhun in #1545

Related to: #1512
898aef6 (widgets) Add example for list by @orhun in #1542

Related to: #1512
452366a (widgets) Add example for sparkline by @orhun in #1556

related #1512

Also removes the sparkline example from ratatui crate since this example is a simplified and easier to understand version of that
6ddde0e (widgets) Add example for table by @orhun in #1557

related #1512
93ad6b8 (widgets) Update values in chart example by @orhun in #1558

better stonks
15f442a (widgets) Add example for paragraph by @orhun in #1544

related #1512

Also removes the paragraph example from ratatui since these examples are more or less the same.
17bba14 (widgets) Move the logo example to widgets by @orhun in #1543

related #1512

Also updates the code to make it consistent with the other examples
f2451e7 (widgets) Add example for gauge by @orhun in #1539

related #1512
4f0a8b2 (widgets) Add example for canvas by @orhun in #1533

related #1512
91147c4 (widgets) Add example for chart by @orhun in #1536

stonks
6dd25a3 (widgets) Add example for calendar by @orhun in #1532

related #1512
99ac005 (widgets) Add simple barchart example by @joshka in #1511
b1d47e7 (uncategorized) Discourage use of Buffer's pos_of, index_of by @pharrison31415 in #2225

These methods assume that the backing store of any buffer / area is linearly indexable. There are other ways that we might want to experiment in the future with how to store the values (trees, 2D allocated areas that are non-contiguous etc.). The index <-> pos conversion there isn't particularly useful. This should be an internal implementation detail of the buffer, rather than something that we expose, but we're not deprecating this for now at least.
f8b0594 (uncategorized) Fix: fix typos by @j-g00da in #2129

This fixes the pipeline after bumping typos.

9998000 (uncategorized) Use shields.io badge by @LitoMore in #2040

Related to:

https://github.com/simple-icons/simple-icons/pull/13593

https://github.com/ratatui/ratatui/pull/1967

The Ratatui icon is available on shields.io now :v:

And it's customizable. There are more configurations at https://shields.io/badges.

Here are some examples:
![](https://img.shields.io/badge/Ratatui-000?logo=ratatui&logoColor=fff)
![](https://img.shields.io/badge/Ratatui-fff?logo=ratatui&logoColor=000)
![](https://img.shields.io/badge/Built_With-Ratatui-000?logo=ratatui&logoColor=fff&labelColor=000&color=fff)
![](https://img.shields.io/badge/Ratatui-000?logo=ratatui&logoColor=fff&style=flat-square)
![](https://img.shields.io/badge/Ratatui-000?logo=ratatui&logoColor=fff&style=for-the-badge)

71ef65b (uncategorized) Add section on collaborative development to contributing doc by @joshka in #2029
cba5cca (uncategorized) Update heading image for Ratatui 0.30.0 release 🎉 by @j-g00da in #2000
9836f07 (uncategorized) Add AI contribution guidelines by @joshka in #2013
98f85b8 (uncategorized) Update link to scrollable widgets RFC by @MatrixFrog in #1994
055522e (uncategorized) Add docs for authoring widget crates by @j-g00da in #1955
- added Authoring Widget Libraries sub-section
- moved built-in and third-party widgets sections higher
617d318 (uncategorized) Improve Block docs by @joshka in #1953
8e2d568 (uncategorized) Improve layout related docs by @joshka in #1948

Adds module level docs and more comprehensive docs on all the types in the layout module

Fixes #1937
4c708dd (uncategorized) Improve docs for run/init/restore etc. by @joshka in #1947
- docs: document the init module
- docs: use the ratatui::run() methods in the main doc
- docs: add more intradoc / website links and historical perspective on Terminal / backend
- docs: add notes about new run/init/restore methods and the defaultterminal type to terminal docs
5620e06 (uncategorized) Add crate organization sections to workspace by @joshka in #1946

Adds summary-level crate organization documentation to all crates explaining the modular workspace structure and when to use each crate. Links to ARCHITECTURE.md for detailed information.
cfb65e6 (uncategorized) Add examples for handling state by @joshka in #1849

Added comprehensive state management examples covering both immutable and mutable patterns and documentation to help developers choose the right approach for their applications.
3de41a8 (uncategorized) Document widgets module by @joshka in #1932
Adds a good overview of the use and implementation of widget traits.

Goals with the doc rewrite:
- document the rationale for the ratatui-widgets crate with info for app builders and widget makers.
- Show how to use the widgets for rendering as well as implement the traits- document the differences and reasons for each trait
- document the historical perspective (to make it easy to understand older Ratatui apps as well as migrate to newer approaches
- give recommended approaches to implementing traits
- explain the differences between Consuming and Shared / Mutable Reference implementations of Widget
- explain the differences between using StatefulWidget and Mutable References
- Explain the use case for WidgetRef and StatefulWidgetRef
- Link out to third part widget lists
Fixes:https://github.com/ratatui/ratatui/issues/366
ca2ad4a (uncategorized) Simplify ratatui-macro docs by @joshka in #1923
92b6a16 (uncategorized) Fix grammar in ratatui-widgets README by @sevki in #1885
da05957 (uncategorized) Add widget-ref-container example by @joshka in #1603

Implements ideas alluded to by https://discord.com/channels/1070692720437383208/1072907135664529508/1323061053990637640 and followup conversations.
1798512 (uncategorized) Fix wording in user_input example by @dawedawe in #1611

Fix wording in user_input.rs example.
03066d8 (uncategorized) Fix punctuation in canvas.rs documentation by @dawedawe in #1583

Fix end of sentence punctuation in canvas.rs docs.
e411d9e (uncategorized) Add input form example by @joshka in #1551

Demonstrates how to manage the cursor and input focus with a simple form. Uses an enum to track the current input field and passes the input events to the active field.

This is similar to the json tutorial on the website, but a bit simpler
ed071f3 (uncategorized) Add mouse-drawing example by @joshka in #1546

Demonstrates how to handle mouse events
46902f5 (uncategorized) Improve docs for workspace crates by @orhun in #1490

Overall makes improvements in the documentation of the workspace crates and checking them.
a6b5792 (uncategorized) Fix example link in readme by @thomas-tacquet in #1462

abe2f27 (backend) Change From impls to new backend specific IntoBackend and FromBackend traits by @joshka in #1464 [breaking]

Adds two traits IntoCrossterm and FromCrossterm for converting between ratatui and crossterm types. This is necessary in order to avoid the orphan rule when implementing From for crossterm types once the crossterm types are moved to a separate crate.

Similarly Termwiz and Termwiz gain FromTermion, IntoTermion, FromTermwiz and IntoTermwiz traits.

BREAKING CHANGE:The From and Into impls for backend types are now replaced with specific backend traits.
+ use ratatui::backend::{FromCrossterm, IntoCrossterm};

let crossterm_color = crossterm::style::Color::Black;
- let ratatui_color = crossterm_color.into();
- let ratatui_color = ratatui::style::Color::from(crossterm_color);
+ let ratatui_color = ratatui::style::Color::from_crossterm(crossterm_color);
- let crossterm_color = ratatui_color.into();
- let crossterm_color = crossterm::style::Color::from(ratatui_color);
+ let crossterm_color = ratatui_color.into_crossterm();

let crossterm_attribute = crossterm::style::types::Attribute::Bold;
- let ratatui_modifier = crossterm_attribute.into();
- let ratatui_modifier = ratatui::style::Modifier::from(crossterm_attribute);
+ let ratatui_modifier = ratatui::style::Modifier::from_crossterm(crossterm_attribute);
- let crossterm_attribute = ratatui_modifier.into();
- let crossterm_attribute = crossterm::style::types::Attribute::from(ratatui_modifier);
+ let crossterm_attribute = ratatui_modifier.into_crossterm();
Similar conversions for ContentStyle -> Style and Attributes -> Modifier exist for Crossterm, and all the Termion and Termwiz types.

0a47ebd (bencher) Update bencher CLI usage by @epompeii in #1470
b46778d (breaking-changes) Add details to no_std-related breaking changes by @j-g00da in #1828
Some corrections and added details to BREAKING-CHANGES.md.

I decided to remove:
- Backend now uses Self::Error for error handling instead of std::io::Error
- Terminal<B> now uses B::Error for error handling instead of std::io::Error
...as we are still using std::io::Error in built-in backends, so this will only be breaking if a third-party backend decides to use a custom error other than std::io::Error, which would be a breaking change in downstream and not ratatui.

The exception to that is TestBackend, which uses Infallible, but this already has its own breaking changes entry.
a0979d6 (build) Remove cargo lint by @joshka in #1549

Duplicate crate lint is too noisy and sensitive to upstream changes
3812f69 (cargo) Update the documentation metadata for crates by @orhun in #2170

also follows the same format for the entries (name -> version -> description -> etc. in order)
ae43ea7 (cell) Use Option instead of space (" ") for symbol by @joshka
This change makes the Cell::symbol field an Option<CompactString>, allowing it to represent an empty cell as None instead of an empty string. The rationale for this is to later allow the merge symbol functionality to act differently based on whether a cell has previously held a symbol or not, rather than always merging with an empty string. This will help make it possible to merge borders with titles with spaces and other symbols, without assuming that an empty string is always equivalent to no symbol.
- Default is now derived as Option::None works correctly.
- PartialEq and Eq implementations are updated to treat None the same as an empty string.
- merge_symbol against an empty cell will now just set the symbol rather than calling MergeStrategy::merge with an empty string.
- PartialEq, and Hash are manually implemented instead of being derived, and are updated to treat None equal to an empty string.
0fbefe9 (ci) Don't fail on cargo-deny advisories by @joshka in #2237

Instead of failing on advisories, run the cargo-deny check, and report the failure.

Uses the cargo-deny-action instead of installing this manually.

https://github.com/EmbarkStudios/cargo-deny-action/tree/v2?tab=readme-ov-file#recommended-pipeline-if-using-advisories-to-avoid-sudden-breakages (bumped to use rust stable, and log level info)
887a636 (ci) Override RUSTUP_TOOLCHAIN for the check step by @ognis1205 in #2116
Summary Fixes an issue where the "check" CI jobs for MSRV and stable were unintentionally using the stable toolchain from rust-toolchain.toml instead of the matrix-specified toolchain.

Details
- Added RUSTUP_TOOLCHAIN: ${{ matrix.toolchain }} to the "check" job in CI configuration.
Additional Context
- https://github.com/ratatui/ratatui/pull/2106
https://discord.com/channels/1070692720437383208/1072879985762762812/1422345357131780177
- https://rust-lang.github.io/rustup/overrides.html#overrides
34baaf1 (ci) Override the toolchain for CI runs by @ognis1205 in #2106
Summary

Fixes an issue where the beta CI jobs were unintentionally using the stable toolchain from rust-toolchain.toml instead of the matrix-specified toolchain. This caused clippy to run against the wrong version.

Details
- Added RUSTUP_TOOLCHAIN: ${{ matrix.toolchain }} to the CI configuration
Additional Context
https://discord.com/channels/1070692720437383208/1072879985762762812/1421990770482745415
- https://rust-lang.github.io/rustup/overrides.html#overrides
e48aa9e (ci) Stop publish-alpha from running on forks by @j-g00da in #1916

I can't sleep because every Saturday alpha release fails on my ratatui fork. This should fix my insomnia.
b3f3c9b (ci) Disable running release-plz on forked repositories by @orhun in #1730

See https://github.com/jdssl/ratatui/pull/1#issuecomment-2739366609
eaa4038 (ci) Install pre-built binaries for cargo-rdme by @orhun in #1477

install-action uses cargo-binstall to install the pre-built binaries of cargo-rdme (which was released in https://github.com/orium/cargo-rdme/releases/tag/v1.4.7).

This will make the check-readme step faster in CI (now takes only 10 seconds).
e5e2316 (ci) Add check for keeping README.md up-to-date by @orhun in #1473
2ef3583 (ci) Replace cargo-make with a custom cargo-xtask by @joshka in #1461

This removes the need for cargo-make and replaces it with a custom xtask binary. See https://github.com/matklad/cargo-xtask for info.

Rearranges the CI workflow to use the new xtask and simplify which workflows that run.
98df774 (core) Move core types to ratatui-core by @joshka in #1460

The buffer, layout, style, symbols, text, and the top level of widgets modules are moved to ratatui-core. This is the first step in modularizing the library so that the core types can be used in other projects without the need for the backend / widgets types.

This helps reduce the need for updating other crates as often due to semver changes outside of the core types.
35eba76 (example) Move demo2 to top level folder by @joshka in #1524
5f57d35 (examples) Add colors explorer demo app by @orhun in #1580

related #1512

Moves the colors examples to apps
5c021bf (examples) Add chart demo app by @orhun in #1579

related #1512

Moves the chart example to apps
9721300 (examples) Add canvas demo app by @orhun in #1578

related #1512

This moves the canvas example to the apps and adds some interactivity via changing the marker by pressing enter.
a6a1368 (examples) Add calendar explorer demo app by @orhun in #1571

Related to #1512

As discussed, this moves the calendar example from ratatui to app examples as an "explorer" example. It also adds interactivity where you can press s to toggle between different styles of calendars.
819e92c (examples) Add weather demo app by @orhun in #1567

related to #1512
b5f7e44 (examples) Move async example to apps by @joshka in #1503

Move async example to examples/apps/async as full project. Simplify a little by removing the need for the github api token.
17316ec (github) Enable sponsorship button by @orhun in #1478
d02995f (gitignore) Add .env to .gitignore by @j-g00da in #1949
b4a71e5 (lint) Add std instead of core/alloc lints to ratatui-widgets by @j-g00da in #1763

Resolves #1761
cef617c (lint) Add std instead of core/alloc lints to ratatui-core by @j-g00da in #1759

Resolves #1752
d3f01eb (lint) Ensure lint config is correct by @joshka in #1528
- Move lints to workspace manifest
- Add lint config to backend crates
- Fix one small lint error
9fb0544 (release) Initialize release-plz by @orhun in #1550

See https://github.com/ratatui/ratatui/pull/1550
60a8191 (widgets) Move crossterm to dev-dependencies by @j-g00da in #1834

Crossterm in widgets is used only in tests.
2b7ec5c (widgets) Enable calendar widget as default by @orhun in #1521

We now expect that you disable the default features if you want less dependencies
714c658 (workspace) Use ratatui dependency from the workspace by @orhun in #2169

Fix #2166
d201b8e (xtask) Check lints for only library targets by @orhun in #1531

Makes it possible to filter workspace packages by their targets. (e.g. when we want to retrieve all the binary targets / examples, etc.)
b7ecef0 (uncategorized) Expose crossterm 0.28/0.29 feature flags in Ratatui by @orhun in #2270
In docs we currently say that individual versions of crossterm could be enabled like this:
```
ratatui = { version = "0.30.0-beta", features = ["crossterm_0_28"] }
```
However this wasn't actually possible:
```
package `x` depends on `ratatui` with feature `crossterm_0_28` but `ratatui` does not have that feature.

failed to select a version for `ratatui` which could resolve this conflict
```
This PR fixes that by exposing respective feature flags. (Tested locally)
297d264 (uncategorized) Update maintainers by @orhun in #2122
91fa249 (uncategorized) Remove obsolete doc_auto_cfg feature by @ognis1205 in #2103

The doc_auto_cfg feature was incorporated into the doc_cfg feature in https://github.com/rust-lang/rust/pull/138907

Closes #2102
46e7c6c (uncategorized) Document rustfmt options by @joshka in #2055
719badb (uncategorized) Skip alpha and beta tags in cliff.toml by @j-g00da in #2026

https://github.com/ratatui/ratatui/pull/2025#issuecomment-3135177683
0afb1a9 (uncategorized) Ignore beta and rc tags in cliff.toml by @j-g00da in #2025
5ae224b (uncategorized) Prepare for beta release by @j-g00da in #2022
cfebd68 (uncategorized) Fix typo in CONTRIBUTING.md by @kdheepak in #2001
Removes a hanging opening code block:
```
```suggestion
```
572749f (uncategorized) Update contributing guidelines and add copilot-instructions by @joshka in #1998

See https://docs.github.com/en/copilot/how-tos/agents/copilot-code-review/using-copilot-code-review

These instructions will be used by copilot when it performs automated PR reviews, and helps provide guardrails for our standards. Over time we might grow these to capture any consistent problems that we start seeing when reviewing.
0148b62 (uncategorized) Remove cargo_metadata dep from xtask by @joshka in #1993

Removed due to hard N-2 MSRV requirement, whereas we use a soft N-2 (only update when necessary). This makes it painful to be able to test our actual msrv (as the xtask has to be built with the version that its deps support, while still wanting to check the msrv version, so we'd end up with 2 versions in the one CI task and this would get annoying to check).

See https://github.com/rust-lang/cargo/issues/15746 for more details.

Partially implements #1820 - mainly as a problem solution rather than a specific goal to use cargo-hack
9bc5739 (uncategorized) Remove clap-cargo from xtask by @joshka in #1992

Removed to avoid needing to bump our msrv. See https://github.com/rust-lang/cargo/issues/15746#issuecomment-3071774343 for more details.
0e10170 (uncategorized) Change Borders::NONE to a proper const by @joshka in #1985

https://docs.rs/bitflags/latest/bitflags/#zero-bit-flags

Flags with no bits set should be avoided because they interact strangely with

Flags::contains and

Flags::intersects. A zero-bit flag is always contained, but is never intersected. The names of zero-bit flags can be parsed, but are never formatted.

Removing this simplifies the manual Debug impl that previously had to check for Borders::NONE and now does not.
8e3bd11 (uncategorized) Add svg logo asset by @LitoMore in #1967
Added a shields.io style svg logo and a nicer version of the original logo. The simplified icon will be added and available directly from shields.io via:
- https://github.com/simple-icons/simple-icons/pull/13593
92bb9b2 (uncategorized) Remove Title references by @j-g00da in #1943
d6647db (uncategorized) Remove some allow attributes for fixed clippy bugs by @joshka in #1944
3f48bde (uncategorized) Remove OpenSSL license by @joshka in #1942

Only keep licenses in the allow list that are actually used
4c86513 (uncategorized) Remove block::Title by @joshka in #1926
The title alignment is better expressed in the Line as this fits more coherently with the rest of the library.

BREAKING CHANGES:
- widgets::block is no longer exported
- widgets::block::Title no longer exists
- widgets::block::Position is now widgets::TitlePosition
- Block::title() now accepts Into::<Line> instead of Into<Title>
- BlockExt is now exported at widgets::BlockExt
Closes:https://github.com/ratatui/ratatui/issues/738
272f5c0 (uncategorized) Fix new lints by @joshka in #1922
770cb7c (uncategorized) Add tests for combining list styles by @joshka in #1884
dbfb2c3 (uncategorized) Upgrade to Rust Edition 2024 by @MatrixFrog in #1863

https://doc.rust-lang.org/edition-guide/rust-2024/index.html

Fixes #1727
7cb35d4 (uncategorized) Update to Rust version 1.85.0 by @MatrixFrog in #1860

This is a small step toward fixing #1727
a07f5be (uncategorized) Move dependency management to workspace by @joshka in #1858
Move all dependency management to the workspace level. This makes it easier to manage dependencies across multiple crates in the workspace.

This also changes the versions of each dependency to track based on the semver compatible version of the dependency (e.g. 0.1 instead of 0.1.0 or 2.9 instead of 2.9.0 to avoid having to regularly update the toml files and to communicate that Ratatui will still generally work with versions of the dependencies that are not the fully latest version. The exact version of the dependencies is still tracked in the Cargo.lock file.

Several dependencies that are fairly stable are changed to track a less specific version (e.g. serde 1 instead of 1.0.x).

The following dependencies are updated to their latest versions:
- bitflags (2.3 -> 2.9)
- strum (0.26 -> 0.27)
- strum_macros (0.26 -> 0.27)
- all other semver compatible updates
1874b9d (uncategorized) Move time to dev-dependencies by @j-g00da in #1835
d88cd29 (uncategorized) Add 'const' to functions where possible. by @MatrixFrog in #1802

The Clippy check for this (missing_const_for_fn) is already enabled, but catches more cases in upcoming toolchain versions.

This is part of the work to unblock #1727
bb06889 (uncategorized) Fix io_other_error clippy lints by @joshka in #1756

Pre-emptive fix for new lint to be added in 1.87 (currently in beta).

https://rust-lang.github.io/rust-clippy/master/index.html#io_other_error
0f80c5e (uncategorized) Use expect() instead of allow() for lint overrides by @cgzones in #1786 [breaking]

BREAKING CHANGE:MSRV is now 1.81
fe8577c (uncategorized) Remove paste dependency by @joshka in #1713

The paste crate is no longer maintained. Replaces the usages of this in the Stylize declarative macros with hard coded values. These macros are internal implementation detail to ratatui and so the changes should have no impact on users.

Fixes:https://github.com/ratatui/ratatui/issues/1712
255e466 (uncategorized) Cargo update - pull in fixed version of ring crate by @joshka in #1710
f05feac (uncategorized) Sort dependencies in Cargo.toml by @canac in #1662
7eab88f (uncategorized) Remove unused deps by @joshka in #1661
37a1c6f (uncategorized) Remove some examples by @orhun in #1645
6f21319 (uncategorized) Rename examples with clashing names by @joshka in #1597

These will eventually be moved / consolidated elsewhere, but this clears the warnings while building for now.
11cbb2b (uncategorized) Use cargo xtask for bacon clippy command by @joshka in #1592
b544e39 (uncategorized) Use clap instead of argh for demo example by @joshka in #1591
9a54198 (uncategorized) Make source files non-executable by @orhun in #1577
```
find . -type f -not -path './.git/*' -not -name '*.bash' -exec chmod 644 {} +
```
fixes #1576
357ae7e (uncategorized) Move terminal types to ratatui-core by @joshka in #1530 [breaking]
- Move Terminal, TerminalOptions, ViewPort, CompletedFrame, Frame to ratatui-core crate
- Move render_widget_ref() and render_stateful_widget_ref() to extension trait (FrameExt) due as the Ref types are unstable and kept in the main lib instead of -core
- Fix rustdoc errors / feature config issues
BREAKING CHANGE:to call Frame::render_widget_ref() or

Frame::render_stateful_widget_ref() you now need to import the FrameExt trait from ratatui::widgets and enable the unstable-widget-ref feature.
21e62d8 (uncategorized) Move the demo example to main folder by @joshka in #1523

Add a top level examples folder for more app-ish examples Move the demo example into the top level folder.
fbf6050 (uncategorized) Prepare alpha modularization release by @joshka in #1525

This is the first modularization -alpha release. It captures the changes necessary to manual publish. And ensures all the crates are properly setup and to set a baseline for comparison in future release checks etc.

This does not update / check the git-cliff setup / changelog

Part of: #1388
e4e95bc (uncategorized) Remove --color always flags from bacon.toml by @joshka in #1502

No longer necessary as of bacon 3.3
a41c97b (uncategorized) Move unstable widget refs to ratatui by @joshka in #1491 [breaking]
These are less stable than the non-ref traits as we have not yet committed to the exact API. This change moves them to ratatui from ratatui-core.

To facilitate this:
- implementations of WidgetRef for all internal widgets are removed and replaced with implementations of Widget for references to those widgets.
- Widget is now implemented for Option where W: Widget, allowing for rendering of optional widgets.
- The blanket implementation of Widget for WidgetRef is reversed, to be a blanket implementation of WidgetRef for all &W where W: Widget.
BREAKING CHANGE:implementations of WidgetRef no longer have a blanket implementation of Widget, so Widgets should generally implement the Widget trait on a reference to the widget rather than implementing WidgetRef directly. This has the advantage of not requiring unstable features to be enabled.

Part of: https://github.com/ratatui/ratatui/issues/1388
e7085e3 (uncategorized) Move widgets into ratatui-widgets crate by @joshka in #1474

All the widgets now live in their own ratatui-widgets crate, but are re-exported in the main ratatui crate. This makes it easier to use portions of the ratatui library and is part of the effort to modularize

Part of: #1388
f1d0a18 (uncategorized) Move ratatui crate into workspace folder by @joshka in #1459

This is the first step towards modularization. Handling the move as a separate step rather than combining it should make it easier to rebase other PRs when necessary.
55fb2d2 (uncategorized) Update repo links to ratatui instead of ratatui-org by @joshka in #1458

@sxyazi made their first contribution in #2267
@pharrison31415 made their first contribution in #2252
@sbarral made their first contribution in #2235
@j-g00da made their first contribution in #2236
@WaterWhisperer made their first contribution in #2221
@0xb002f0 made their first contribution in #2223
@matthiasbeyer made their first contribution in #2212
@b-guild made their first contribution in #2197
@github-actions[bot] made their first contribution in #2162
@marcoieni made their first contribution in #2119
@Blaeriz made their first contribution in #2071
@ognis1205 made their first contribution in #2116
@isgin01 made their first contribution in #2100
@nornagon made their first contribution in #2063
@lolbinarycat made their first contribution in #2088
@rcorre made their first contribution in #2057
@martinetd made their first contribution in #2053
@kashregister made their first contribution in #2043
@LitoMore made their first contribution in #2040
@aschey made their first contribution in #2004
@dtolnay made their first contribution in #1999
@MatrixFrog made their first contribution in #1994
@jwodder made their first contribution in #1670
@acuteenvy made their first contribution in #1956
@harilvfs made their first contribution in #1905
@Daksh14 made their first contribution in #1891
@sevki made their first contribution in #1885
@aurreland made their first contribution in #1883
@ArjunKrish7356 made their first contribution in #1812
@cgzones made their first contribution in #1789
@ed-2100 made their first contribution in #1782
@musicinmybrain made their first contribution in #1783
@LecrisUT made their first contribution in #1777
@canac made their first contribution in #1662
@LVivona made their first contribution in #1639
@alexpasmantier made their first contribution in #1622
@theotchlx made their first contribution in #1573
@dawedawe made their first contribution in #1611
@Its-Just-Nans made their first contribution in #1584
@MarSik made their first contribution in #1541
@raylu made their first contribution in #1540
@renesat made their first contribution in #1501
@HoKim98 made their first contribution in #1484
@nilsmartel made their first contribution in #1485
@epompeii made their first contribution in #1470
@thomas-tacquet made their first contribution in #1462

ratatui

Related Projects

mapbox-navigation-android

ToastFish

barcodelib

haze

ratatui-termwiz-v0.1.0

Features

Related Projects

mapbox-navigation-android

ToastFish

barcodelib

haze

Bug Fixes

Refactor

This commit does the following:

Explanation:

Documentation

Performance

Styling

Summary

Testing

Overview

Changes

Impact

Notes

Miscellaneous Tasks

Summary

Details

Additional Context

Continuous Integration

Reverted Commits

New Contributors