v0.25.0

[orhun]

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!

• @rikonaka
• @danny-burrows
• @SOF3
• @jan-ferdinand
• @rhaskia
• @asomers
• @progval
• @TylerBloom
• @YeungKC
• @lyuha

---

This discussion was created from the release v0.25.0.