Ratatui: Layout, Widgets & Styling

Each segment is sized by one Constraint. When the constraints cannot all be satisfied (an 80-column terminal asked for 100 columns of fixed content), the solver follows a fixed priority.

Percentage and Ratio are computed against the whole space being divided, not the space left after the fixed segments, so [Length(10), Percentage(50)] of 100 columns gives 10 and 50, not 10 and 45. A third cannot be written as a percentage, so use Ratio(1, 3) or Fill(1) for it. Constraint::default() is Percentage(100), and a plain u16 converts into Length. Helpers from_lengths, from_percentages, from_ratios, from_mins, from_maxes and from_fills build a Vec of one kind of constraint from numbers. The Fill constraint is the one to prefer for the flexible region of a screen, because it expresses "the rest" explicitly and composes with other Fill weights ([Fill(1), Fill(2)] gives a one-third / two-thirds split).

Flex decides where the excess space goes when the constraints leave some over.

Source: docs.rs — ratatui::layout::Layout

On an 80 x 24 terminal the vertical layout yields Rect { x: 0, y: 0, width: 80, height: 3 }, a 20-row body and a one-row footer; the horizontal split then gives the list roughly 40 percent of the width and the details pane the rest, minus the one-cell gap. The rectangles in the figure are rounded for readability, so tests should assert on rendered content rather than on exact widths computed by hand. Margin is written as a struct literal with vertical and horizontal fields, the form the official pages use.

Source: docs.rs — ratatui::layout::Constraint and docs.rs — ratatui::layout::Flex

Ratatui models styled text in three layers, and every widget that shows text accepts anything convertible to them, so a plain &str or String works until styling is needed.

Masked wraps a string so that it is displayed as a mask character (for a password field); StyledGrapheme is the rendering-level unit and is not part of the Span / Line / Text hierarchy; the ToSpan, ToLine and ToText traits convert values to each layer. Alignment set on a Line overrides the alignment of the Text or Paragraph that contains it. A Span never wraps and never contains a newline: embedding \n in a span is a bug, build a Text.

Source: docs.rs — ratatui::text

A Style is a set of optional changes: a foreground colour, a background colour, an underline colour and the added and removed Modifier flags. Styles are incremental: when several styles are applied to the same cell (the block, then the list, then the item, then the highlight), the cell ends up with the merge of all of them, with later styles winning on the properties they set. Style::default() changes nothing; Style::reset() resets every property at that point of the sequence.

Source: docs.rs — ratatui::style

Stylize is implemented for every type that implements Styled: &str, String, Span, Line, Style and most widgets, so Paragraph::new("x").red() and Block::bordered().blue() work. Its shorthands are named after the colour (red(), dark_gray(), light_blue()), prefixed with on_ for backgrounds, and come in pairs for the modifiers (bold() and not_bold(), dim, italic, underlined, slow_blink, rapid_blink, reversed, hidden, crossed_out).

Color also parses from strings ("light red", "#FF0000", "10" for an indexed colour), which is how colours read from a configuration file are turned into styles. The nine Modifier flags (BOLD, DIM, ITALIC, UNDERLINED, SLOW_BLINK, RAPID_BLINK, REVERSED, HIDDEN, CROSSED_OUT) are bit flags that combine with |.

Block draws borders, titles and padding around other widgets and is the container almost every other widget accepts through its block(...) method. Block::bordered() is Block::new().borders(Borders::ALL); borders takes flags that combine with | (Borders::LEFT | Borders::RIGHT).

Source: docs.rs — ratatui::widgets::Block and docs.rs — BorderType

The border glyphs are Unicode box-drawing characters. They render correctly in Windows Terminal, in macOS Terminal and in modern Linux terminals; the legacy Windows console (conhost) with a raster font may show replacement glyphs for the rounded, dashed and quadrant sets, in which case BorderType::Plain is the safe choice. The ambiguous-width and double-width character problems explained on the escape-sequences page affect titles containing CJK or emoji text.

Paragraph::new takes anything convertible to Text. Options: block, style (the whole widget including the block), wrap(Wrap { trim }), scrolly, x, alignment and its shortcuts left_aligned, centered and right_aligned. Without wrap a long line is truncated at the area’s edge; with Wrap { trim: true } leading whitespace of wrapped lines is dropped, and with trim: false indentation is preserved. The scroll offset is given as (y, x), the reverse of the order used elsewhere in the crate.

Paragraph::line_count(width) and Paragraph::line_width() report the number of rendered lines and the narrowest width that avoids breaking a word, including the block. Both require the unstable-rendered-line-info feature, which the official page marks as having no stability guarantees; without them, scroll limits for wrapped text have to be estimated by hand.

Source: docs.rs — ratatui::widgets::Paragraph and docs.rs — Wrap

List::new takes any iterator of items convertible to ListItem (a &str, a Text or a Line works). It is a StatefulWidget whose state is a ListState.

ListState holds the selected index and the scroll offset. Create it once and keep it in the application state, not in the draw function, otherwise the selection resets on every frame. Its API: selected(), select(Option<usize>) (which also resets the offset to 0), select_next(), select_previous(), select_first(), select_last(), scroll_down_by(u16), scroll_up_by(u16), offset(), offset_mut(), with_selected and with_offset. The "last" and "previous" operations store usize::MAX before the first render because the item count is not known yet; the list corrects the index while rendering, so the selection is always valid on screen, but the stored value may be out of range between a key press and the next draw. Read the selected index only after a draw, or clamp it against the length of your own collection.

Table::new(rows, widths) takes rows (anything convertible to Row, built from cells convertible to Cell) and one Constraint per column. Without widths, columns are equal.

Row has height, top_margin, bottom_margin and style and Cell takes any Text, so a row can be taller than one line. TableState extends the list state with columns: selected(), selected_column(), selected_cell(), select, select_column, select_cell, select_next, select_next_column, select_previous, select_previous_column, select_first, select_last, scroll_down_by, scroll_up_by, scroll_left_by, scroll_right_by and offset(). The same "corrected during render" rule applies to the relative operations.

Tabs::new(titles) takes titles convertible to Line. Unlike List, Tabs is not stateful: the selection is a builder argument, select(index) (or select(None)), so the application keeps the index and rebuilds the widget every frame. Options: block, style, highlight_style, divider (a pipe by default), padding(left, right), padding_left and padding_right (one space each by default).

Source: docs.rs — ratatui::run, docs.rs — List and docs.rs — Table

The loop is the minimal one from the getting-started page: draw, then block on one event. The popup is drawn last so that it covers everything under it, after Clear has reset its area. The screen runs unchanged on Windows, macOS and Linux because the crossterm backend hides the platform differences, but note the KeyEventKind::Press check: on Windows crossterm reports both key presses and releases, so without it every key would act twice (see Ratatui: Events, Async & Application Architecture).

Gauge is a block-style progress bar. percent(u16) (0 to 100) and ratio(f64) (0.0 to 1.0) set the fill level and both panic when the value is out of range, so clamp computed values first. label(...) replaces the default percentage text, which is centred; gauge_style styles the bar and style styles the background and block; use_unicode(true) uses eight-step partial block characters for sub-cell precision.

LineGauge draws a thin line instead. ratio(f64) (also panicking outside 0 to 1), label(...) (always on the left), filled_symbol, unfilled_symbol, filled_style, unfilled_style, style and block. The older line_set (deprecated in 0.30.0) and gauge_style (deprecated in 0.27.0) should be replaced by the symbol and style methods.

Source: docs.rs — Gauge and docs.rs — LineGauge

Sparkline renders one bar per value in the width of its area. data(...) accepts u64 values, Option<u64> (a None is an absent value drawn with absent_value_symbol, by default the empty shade, and absent_value_style) or SparklineBar values with their own style. max(u64) fixes the scale (otherwise the largest value is used), direction(RenderDirection) renders left to right (default) or right to left, bar_set chooses symbols::bar::NINE_LEVELS (default), THREE_LEVELS or a custom set.

BarChart shows labelled bars, vertical by default. BarChart::new or vertical takes Bar values, horizontal draws horizontal bars, grouped takes BarGroup values and data adds one group at a time. A Bar is created with Bar::with_label(label, value) and may carry its own style and value style; a BarGroup is a labelled set of bars. Options: bar_width and bar_gap (default 1 each; labels never exceed the bar width), group_gap, bar_style, value_style, label_style, bar_set, max (the value that produces a full-height bar), direction, block and style.

Source: docs.rs — Sparkline and docs.rs — BarChart

Chart::new(vec![datasets]) plots one or more Dataset values on two Axis values. A Dataset has name (datasets without a name are left out of the legend), data(&[(f64, f64)]) (the slice must outlive the chart; the Y axis runs from bottom to top as in mathematics), marker, graph_type and style. GraphType is Scatter (the default: only the points), Line (connect consecutive points in dataset order), Bar (a line from the X axis to each point) or Area (a line with the region filled down to fill_to_y, 0.0 by default). An Axis has title, bounds([min, max]), labels(...) (at least two to render; the official page warns that more than three labels is currently broken and middle labels may be misplaced), labels_alignment and style. Chart itself has block, style, legend_position(Option<LegendPosition>) (top right by default, None hides it) and hidden_legend_constraintswidth, height, which hide the legend when it takes more than 25 % of the chart by default.

Source: docs.rs — Chart, docs.rs — Dataset and docs.rs — Axis

The Marker enum (used by Dataset::marker and Canvas::marker, and #[non_exhaustive], so a match needs a wildcard arm) selects how points are drawn: Dot, Block and Bar (one point per cell), Braille (2 x 4 dots per cell, the highest resolution and the canvas default), HalfBlock (twice the vertical resolution, with a foreground and background colour per cell), Quadrant (2 x 2), Sextant (2 x 3), Octant (2 x 4 without gaps between cells) and Custom(char). Braille needs a font that has the Unicode Braille Patterns block, and Sextant and Octant use the "Symbols for Legacy Computing" block, whose support is less widespread than Braille. Windows Terminal, macOS Terminal and the common Linux terminal emulators show Braille; the legacy console host with a raster font may not. Pick Dot or Block when the output must work everywhere.

Canvas draws freeform shapes on a coordinate system independent of the cell grid. Build it with Canvas::default() and the options block, x_bounds([min, max]), y_bounds([min, max]) (changing the bounds zooms into part of the drawing), marker, background_color and paint(closure). The closure receives a Context with draw(&shape), layer() (starts a new layer so later shapes are drawn on top) and print(x, y, text) (text, unaffected by layers). The shapes in ratatui::widgets::canvas are Line, Rectangle, Circle, Points, Map (with MapResolution), FilledLine and Label; any type implementing the Shape trait can be drawn.

Source: docs.rs — Canvas and docs.rs — canvas module

The shapes are plain structs with public fields: Line has x1, y1, x2, y2 and color, Rectangle has x, y, width, height and color, and Circle has x, y, radius and color, all coordinates being f64 in the canvas bounds.

Scrollbar is drawn beside another widget; it does not scroll anything itself. Create it with Scrollbar::new(ScrollbarOrientation::VerticalRight) (or HorizontalBottom, among others), customise it with begin_symbol, end_symbol, track_symbol, thumb_symbol (symbols; an Option for the arrows and track) and the matching *_style methods, symbols(Set), orientation_and_symbol and a single style for all parts. The state is a ScrollbarState: ScrollbarState::new(content_length), then position(n), content_length(n) and viewport_content_length(n), and the in-place prev(), next(), first(), last() and scroll(ScrollDirection). The scrollbar renders blank unless the content length is set before rendering. Render it over the same area as the scrolled widget, shrunk by a vertical margin so that it stays inside a border.

Source: docs.rs — Scrollbar and docs.rs — ScrollbarState

The state is rebuilt from the application’s own scroll position on every frame in the example above, which is the simplest correct pattern: the application owns the position and the scrollbar only displays it.

ratatui::widgets::calendar::Monthly shows the month that contains a given date and is available with the widget-calendar feature (on by default). Dates are time::Date values, so the application depends on the time crate. Monthly::new(display_date, events) takes any DateStyler; the bundled CalendarEventStore is a map from dates to styles (add(date, style), or today(style)). Options: show_surrounding(style) (fills the days of the neighbouring months), show_weekdays_header(style), show_month_header(style), default_style(style) and block. width() and height() report the size the calendar needs. The example below needs time = "0.3" in Cargo.toml next to ratatui.

Source: docs.rs — calendar::Monthly and docs.rs — CalendarEventStore

The official pages do not describe how the calendar chooses the first day of the week or localises month names; the display is fixed by the widget, so a localised calendar has to be drawn with a Table or a custom widget.

Clear is a unit struct that resets every cell of its area so that something can be drawn over it. Render it immediately before a popup, otherwise the cells below show through wherever the popup leaves blanks. The official page points out that Clear cannot be used to clear the terminal on the first render, because Ratatui assumes the area is empty at that point; use Terminal::clear for that.

Fill::new(symbol) paints its whole area with one repeated symbol and style (symbol(...) and style(...) change them); it suits backgrounds, separators and hand-made borders. Shadow is a configurable shadow drawn behind a Block with Block::shadow. Its constructors choose the look: overlay() (style only), block() (full blocks), light_shade(), medium_shade(), dark_shade(), symbol("x") and custom(effect) for a type implementing CellEffect; style(...) sets the shadow’s style and offset(Offset) moves it (positive x to the right, positive y downwards).

Source: docs.rs — Clear, docs.rs — Fill and docs.rs — Shadow

The official pages do not state in which release Fill, Shadow and Block::shadow appeared; treat them as present in 0.30.2 and check the changelog before depending on them from an older version.

RatatuiLogo draws the Ratatui logo on two lines in one of two sizes (RatatuiLogo::tiny(), 2 x 15 cells, the default, and RatatuiLogo::small(), 2 x 27 cells, or new(RatatuiLogoSize)); the documentation suggests it for an "about" or help screen of an application built on Ratatui. RatatuiMascot renders the project’s mascot, with the eye state chosen through MascotEyeColor. Neither is useful for anything but decoration.