Release v0.25.0 · ratatui/ratatui

We are thrilled to announce the new version of ratatui - a Rust library that's all about cooking up TUIs 🐭

In this version, we made improvements on widgets such as List, Table and Layout and changed some of the defaults for a better user experience. Also, we renewed our website and updated our documentation/tutorials to get started with ratatui: https://ratatui.rs 🚀

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

⚠️ List of breaking changes can be found here.

💖 We also enabled GitHub Sponsors for our organization, consider sponsoring us if you like ratatui: https://github.com/sponsors/ratatui-org

Features

aef4956
(list) List::new now accepts IntoIterator<Item = Into<ListItem>> (#672) [breaking]
```
This allows to build list like

```
List::new(["Item 1", "Item 2"])
```
```
8bfd666
(paragraph) Add line_count and line_width unstable helper methods
```
This is an unstable feature that may be removed in the future
```

1229b96
(rect) Add offset method (#533)

The offset method creates a new Rect that is moved by the amount
specified in the x and y direction. These values can be positive or
negative. This is useful for manual layout tasks.

```rust
let rect = area.offset(Offset { x: 10, y -10 });
```

edacaf7
(buffer) Deprecate Cell::symbol field (#624)

The Cell::symbol field is now accessible via a getter method (`symbol()`). This will
allow us to make future changes to the Cell internals such as replacing `String` with
`compact_str`.

6b2efd0
(layout) Accept IntoIterator for constraints (#663)

Layout and Table now accept IntoIterator for constraints with an Item
that is AsRef<Constraint>. This allows pretty much any collection of
constraints to be passed to the layout functions including arrays,
vectors, slices, and iterators (without having to call collect() on
them).

753e246
(layout) Allow configuring layout fill (#633)

The layout split will generally fill the remaining area when `split()`
is called. This change allows the caller to configure how any extra
space is allocated to the `Rect`s. This is useful for cases where the
caller wants to have a fixed size for one of the `Rect`s, and have the
other `Rect`s fill the remaining space.

For now, the method and enum are marked as unstable because the exact
name is still being bikeshedded. To enable this functionality, add the
`unstable-segment-size` feature flag in your `Cargo.toml`.

To configure the layout to fill the remaining space evenly, use
`Layout::segment_size(SegmentSize::EvenDistribution)`. The default
behavior is `SegmentSize::LastTakesRemainder`, which gives the last
segment the remaining space. `SegmentSize::None` will disable this
behavior. See the docs for `Layout::segment_size()` and
`layout::SegmentSize` for more information.

Fixes https://github.com/ratatui-org/ratatui/issues/536

1e2f0be
(layout) Add parameters to Layout::new() (#557) [breaking]

Adds a convenience function to create a layout with a direction and a
list of constraints which are the most common parameters that would be
generally configured using the builder pattern. The constraints can be
passed in as any iterator of constraints.

```rust
let layout = Layout::new(Direction::Horizontal, [
    Constraint::Percentage(50),
    Constraint::Percentage(50),
]);
```

c862aa5
(list) Support line alignment (#599)

The `List` widget now respects the alignment of `Line`s and renders them as expected.

4424637
(span) Add setters for content and style (#647)
ebf1f42
(style) Implement From trait for crossterm to Style related structs (#686)

e49385b
(table) Add a Table::segment_size method (#660)

It controls how to distribute extra space to an underconstrained table.
The default, legacy behavior is to leave the extra space unused.  The
new options are LastTakesRemainder which gets all space to the rightmost
column that can used it, and EvenDistribution which divides it amongst
all columns.

b8f71c0
(widgets/chart) Add option to set the position of legend (#378)

5bf4f52
(uncategorized) Implement From trait for termion to Style related structs (#692)

* feat(termion): implement from termion color

* feat(termion): implement from termion style

* feat(termion): implement from termion `Bg` and `Fg`

d19b266
(uncategorized) Add Constraint helpers (e.g. from_lengths) (#641)

Adds helper methods that convert from iterators of u16 values to the
specific Constraint type. This makes it easy to create constraints like:

```rust
// a fixed layout
let constraints = Constraint::from_lengths([10, 20, 10]);

// a centered layout
let constraints = Constraint::from_ratios([(1, 4), (1, 2), (1, 4)]);
let constraints = Constraint::from_percentages([25, 50, 25]);

// a centered layout with a minimum size
let constraints = Constraint::from_mins([0, 100, 0]);

// a sidebar / main layout with maximum sizes
let constraints = Constraint::from_maxes([30, 200]);
```

Bug Fixes

f69d57c
(rect) Fix underflow in the Rect::intersection method (#678)

56fc410
(block) Make inner aware of title positions (#657)

Previously, when computing the inner rendering area of a block, all
titles were assumed to be positioned at the top, which caused the
height of the inner area to be miscalculated.

ec7b387
(doc) Do not access deprecated Cell::symbol field in doc example (#626)

37c70db
(table) Add widths parameter to new() (#664) [breaking]

This prevents creating a table that doesn't actually render anything.

1f88da7
(table) Fix new clippy lint which triggers on table widths tests (#630)
```
* fix(table): new clippy lint in 1.74.0 triggers on table widths tests
```

36d8c53
(table) Widths() now accepts AsRef<[Constraint]> (#628)

This allows passing an array, slice or Vec of constraints, which is more
ergonomic than requiring this to always be a slice.

The following calls now all succeed:

```rust
Table::new(rows).widths([Constraint::Length(5), Constraint::Length(5)]);
Table::new(rows).widths(&[Constraint::Length(5), Constraint::Length(5)]);

// widths could also be computed at runtime
let widths = vec![Constraint::Length(5), Constraint::Length(5)];
Table::new(rows).widths(widths.clone());
Table::new(rows).widths(&widths);
```

34d099c
(tabs) Fixup tests broken by semantic merge conflict (#665)

Two changes without any line overlap caused the tabs tests to break

e4579f0
(tabs) Set the default highlight_style (#635) [breaking]

Previously the default highlight_style was set to `Style::default()`,
which meant that the highlight style was the same as the normal style.
This change sets the default highlight_style to reversed text.

28ac55b
(tabs) Tab widget now supports custom padding (#629)

The Tab widget now contains padding_left and and padding_right
properties. Those values can be set with functions `padding_left()`,
`padding_right()`, and `padding()` which all accept `Into<Line>`.

Fixes issue https://github.com/ratatui-org/ratatui/issues/502

df0eb1f
(terminal) Insert_before() now accepts lines > terminal height and doesn't add an extra blank line (#596)

Fixes issue with inserting content with height>viewport_area.height and adds
the ability to insert content of height>terminal_height

- Adds TestBackend::append_lines() and TestBackend::clear_region() methods to
  support testing the changes

aaeba27
(uncategorized) Truncate table when overflow (#685)

This prevents a panic when rendering an empty right aligned and rightmost table cell

ffa78aa
(uncategorized) Add #[must_use] to Style-moving methods (#600)
a2f2bd5
(uncategorized) MSRV is now 1.70.0 (#593)

Refactor

f767ea7
(list) start_corner is now direction (#673)

The previous name `start_corner` did not communicate clearly the intent of the method.
A new method `direction` and a new enum `ListDirection` were added.

`start_corner` is now deprecated

b82451f
(examples) Add vim binding (#688)

0576a8a
(layout) To natural reading order (#681)

Structs and enums at the top of the file helps show the interaction
between the types without having to find each type in between longer
impl sections.

Also moved the try_split function into the Layout impl as an associated
function and inlined the `layout::split()` which just called try_split.
This makes the code a bit more contained.

4be18ab
(readme) Reference awesome-ratatui instead of wiki (#689)

* refactor(readme): link awesome-ratatui instead of wiki

The apps wiki moved to awesome-ratatui

* docs(readme): Update README.md

7ef0afc
(widgets) Remove unnecessary dynamic dispatch and heap allocation (#597)

b282a06
(uncategorized) Remove items deprecated since 0.10 (#691) [breaking]

Remove `Axis::title_style` and `Buffer::set_background` which are deprecated since 0.10

7ced7c0
(uncategorized) Define struct WrappedLine instead of anonymous tuple (#608)
```
It makes the type easier to document, and more obvious for users
```

Documentation

fe632d7
(sparkline) Add documentation (#648)
f4c8de0
(chart) Document chart module (#696)
1b8b626
(examples) Add animation and FPS counter to colors_rgb (#583)

2169a0d
(examples) Add example of half block rendering (#687)

This is a fun example of how to render big text using half blocks

41c44a4
(frame) Add docs about resize events (#697)
91c67eb
(github) Update code owners (#666)
```
onboard @Valentin271 as maintainer
```
458fa90
(lib) Tweak the crate documentation (#659)

3ec4e24
(list) Add documentation to the List widget (#669)

Adds documentation to the List widget and all its sub components like `ListState` and `ListItem`

9f37100
(readme) Update README.md and fix the bug that demo2 cannot run (#595)
```
Fixes https://github.com/ratatui-org/ratatui/issues/594
```

2a87251
(security) Add security policy (#676)

* docs: Create SECURITY.md

* Update SECURITY.md

987f7ee
(website) Rename book to website (#661)
a15c3b2
(uncategorized) Remove deprecated table constructor from breaking changes (#698)
113b4b7
(uncategorized) Rename template links to remove ratatui from name 📚 (#690)

211160c
(uncategorized) Remove simple-tui-rs (#651)

This has not been recently and doesn't lead to good code

Styling

6a6e9dd
(tabs) Fix doc formatting (#662)

Miscellaneous Tasks

910ad00
(rustfmt) Enable format_code_in_doc_comments (#695)

This enables more consistently formatted code in doc comments,
especially since ratatui heavily uses fluent setters.

See https://rust-lang.github.io/rustfmt/?version=v1.6.0#format_code_in_doc_comments

d118565
(table) Cleanup docs and builder methods (#638)

- Refactor the `table` module for better top to bottom readability by
putting types first and arranging them in a logical order (Table, Row,
Cell, other).

- Adds new methods for:
  - `Table::rows`
  - `Row::cells`
  - `Cell::new`
  - `Cell::content`
  - `TableState::new`
  - `TableState::selected_mut`

- Makes `HighlightSpacing::should_add` pub(crate) since it's an internal
  detail.

- Adds tests for all the new methods and simple property tests for all
  the other setter methods.

dd22e72
(uncategorized) Correct "builder methods" in docs and add must_use on widgets setters (#655)

18e19f6
(uncategorized) Fix breaking changes doc versions (#639)

Moves the layout::new change to unreleasedd section and adds the table change

a58cce2
(uncategorized) Disable default benchmarking (#598)

Disables the default benchmarking behaviour for the lib target to fix unrecognized
criterion benchmark arguments.

See https://bheisler.github.io/criterion.rs/book/faq.html#cargo-bench-gives-unrecognized-option-errors-for-valid-command-line-options for details

Continuous Integration

59b9c32
(codecov) Adjust threshold and noise settings (#615)
```
Fixes https://github.com/ratatui-org/ratatui/issues/612
```
03401cd
(uncategorized) Fix untrusted input in pr check workflow (#680)

Contributors

Thank you so much to everyone that contributed to this release!

Here is the list of contributors who have contributed to ratatui for the first time!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

v0.25.0

Features

Bug Fixes

Refactor

Documentation

Styling

Miscellaneous Tasks

Continuous Integration

Contributors

Contributors