Crate ratatui_widgets 

ratatui-widgets contains all the widgets that were previously part of the Ratatui crate. It is meant to be used in conjunction with ratatui, which provides the core functionality for building terminal user interfaces.

Most applications shouldn’t need to depend directly on ratatui-widgets, ratatui crate re-exports all the widgets from this crate. However, if you are building a widget library that internally uses these widgets, or if you prefer finer grained dependencies, you may want to depend on this crate rather than transitively through the ratatui crate.

Previously, a crate named ratatui-widgets was published with some formative ideas about an eventual Ratatui framework. That crate has now moved to tui-framework-experiment, pending a new name.

Installation

Run the following command to add this crate to your project:

cargo add ratatui-widgets

Available Widgets

• BarChart: displays multiple datasets as bars with optional grouping.
• Block: a basic widget that draws a block with optional borders, titles, and styles.
• calendar::Monthly: displays a single month.
• Canvas: draws arbitrary shapes using drawing characters.
• Chart: displays multiple datasets as lines or scatter graphs.
• Clear: clears the area it occupies. Useful to render over previously drawn widgets.
• Gauge: displays progress percentage using block characters.
• LineGauge: displays progress as a line.
• List: displays a list of items and allows selection.
• RatatuiLogo: displays the Ratatui logo.
• RatatuiMascot: displays the Ratatui mascot.
• Paragraph: displays a paragraph of optionally styled and wrapped text.
• Scrollbar: displays a scrollbar.
• Sparkline: displays a single dataset as a sparkline.
• Table: displays multiple rows and columns in a grid and allows selection.
• Tabs: displays a tab bar and allows selection.

All these widgets are re-exported directly under ratatui::widgets in the ratatui crate.

Crate Organization

ratatui-widgets is part of the Ratatui workspace that was modularized in version 0.30.0. This crate contains all the built-in widget implementations that were previously part of the main ratatui crate.

When to use ratatui-widgets:

• Building widget libraries that need to compose with built-in widgets
• You want finer-grained dependencies and only need specific widgets
• Creating custom widgets that extend or wrap the built-in ones

When to use the main ratatui crate:

• Building applications (recommended - includes everything you need)
• You want the convenience of having all widgets available

For detailed information about the workspace organization, see ARCHITECTURE.md.

Features

• std — enables std
• serde — 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.

Widgets that add dependencies are gated behind feature flags to prevent unused transitive dependencies. The available features are:

• all-widgets (enabled by default) — enables all widgets.
• calendar (enabled by default) — enables the calendar widget module and adds a dependency on time.
• unstable — Enable all unstable features.
• unstable-rendered-line-info — Enables the Paragraph::line_count Paragraph::line_width methods which are experimental and may change in the future. See Issue 293 for more details.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub. For more details on contributing, please see the CONTRIBUTING document.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Modules

barchart

The BarChart widget and its related types (e.g. Bar, BarGroup).

block

Elements related to the Block base widget.

borders

Border related types (Borders, BorderType) and a macro to create borders (border).

calendarcalendar

A simple calendar widget. (feature: widget-calendar)

canvas

A Canvas and a collection of Shapes.

chart

The Chart widget is used to plot one or more Dataset in a cartesian coordinate system.

clear

The Clear widget allows you to clear a certain area to allow overdrawing (e.g. for popups).

gauge

The Gauge widget is used to display a horizontal progress bar.

list

The List widget is used to display a list of items and allows selecting one or multiple items.

logo

The RatatuiLogo widget renders the Ratatui logo.

mascot

A Ratatui mascot widget

paragraph

The Paragraph widget and related types allows displaying a block of text with optional wrapping, alignment, and block styling.

scrollbar

The Scrollbar widget is used to display a scrollbar alongside other widgets.

sparkline

The Sparkline widget is used to display a sparkline over one or more lines.

table

The Table widget is used to display multiple rows and columns in a grid and allows selecting one or multiple cells.

tabs

The Tabs widget displays a horizontal set of tabs with a single tab selected.

Macros

border

Macro that constructs and returns a combination of the Borders object from TOP, BOTTOM, LEFT and RIGHT.