Ratatui

https://docs.rs/ratatui/latest
Admin
Ratatui is a lightweight Rust crate for building complex terminal user interfaces with widgets,...
Tokens:1,344,682
Snippets:12,065
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Quickstart Example

Source: https://docs.rs/ratatui/latest/src/ratatui/lib.rs.html?search=u32+-%3E+bool

A minimal example of a Ratatui application that renders a widget and handles key events.

```rust
use crossterm::event;

fn main() -> std::io::Result<()> {
    ratatui::run(|mut terminal| {
        loop {
            terminal.draw(|frame| frame.render_widget("Hello Ratatui!", frame.area()))?;
            if crossterm::event::poll(std::time::Duration::from_millis(250))? {
                if let crossterm::event::Event::Key(key) = crossterm::event::read()? {
                    if key.kind == crossterm::event::KeyEventKind::Press {
                        return Ok(());
                    }
                }
            }
        }
    })
}
```

--------------------------------

### Start Flex Examples

Source: https://docs.rs/ratatui/latest/ratatui/layout/enum.Flex.html

Visual examples of items aligned to the start of the container.

```text
<------------------------------------80 px------------------------------------->
┌────16 px─────┐┌──────20 px───────┐┌──────20 px───────┐
│Percentage(20)││    Length(20)    ││     Fixed(20)    │
└──────────────┘└──────────────────┘└──────────────────┘

<------------------------------------80 px------------------------------------->
┌──────20 px───────┐┌──────20 px───────┐
│      Max(20)     ││      Max(20)     │
└──────────────────┘└──────────────────┘

<------------------------------------80 px------------------------------------->
┌──────20 px───────┐
│      Max(20)     │
└──────────────────┘
```

--------------------------------

### Start: alignment example

Source: https://docs.rs/ratatui/latest/ratatui/prelude/layout/enum.Flex.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example for the `Start` variant: aligns items to the start of the container. Shows how `Min(20)` and `Max(20)` constraints are placed at the start.

```text
<------------------------------------80 px------------------------------------->
┌────────────────────────60 px───────────────────────────┐┌──────20 px───────┐
│                          Min(20)                         ││      Max(20)     │
└──────────────────────────────────────────────────────────┘└──────────────────┘

<------------------------------------80 px------------------------------------->
┌────────────────────────────────────80 px─────────────────────────────────────┐
│                                    Max(20)                                   │
└──────────────────────────────────────────────────────────────────────────────┘

```

--------------------------------

### Quickstart example

Source: https://docs.rs/ratatui/latest/src/ratatui/lib.rs.html

Example of using ratatui::run to initialize the terminal, run the application, and restore the terminal on exit.

```rust
use crossterm::event;

fn main() -> std::io::Result<()> {
    ratatui::run(|terminal| {
        terminal.draw(|frame| {
            // rendering code here
        });
    })
}
```

--------------------------------

### Start flex example with Percentage, Length, and Fixed constraints

Source: https://docs.rs/ratatui/latest/ratatui/layout/enum.Flex.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how the Start flex mode aligns items to the start of the container, distributing excess space after the last item.

```code
<------------------------------------80 px------------------------------------->
┌────16 px─────┐┌──────20 px───────┐┌──────20 px───────┐
│Percentage(20)││    Length(20)    ││     Fixed(20)    │
└──────────────┘└──────────────────┘└──────────────────┘

<------------------------------------80 px------------------------------------->
┌──────20 px───────┐┌──────20 px───────┐
│      Max(20)     ││      Max(20)     │
└──────────────────┘└──────────────────┘

<------------------------------------80 px------------------------------------->
┌──────20 px───────┐
│      Max(20)     │
└──────────────────┘
```

--------------------------------

### Quickstart: Add dependencies and run a Hello World app

Source: https://docs.rs/ratatui/latest/ratatui/index.html?search=

Adds the ratatui and crossterm dependencies, then shows a minimal "Hello World" application using ratatui::run. The app draws the text "Hello World!" and exits when a key is pressed. This is the quickstart example from the crate documentation.

```bash
cargo add ratatui crossterm
```

```rust
use crossterm::event;

fn main() -> std::io::Result<()> {
    ratatui::run(|mut terminal| {
        loop {
            terminal.draw(|frame| frame.render_widget("Hello World!", frame.area()))?;
            if event::read()?.is_key_press() {
                break Ok(());
            }
        }
    })
}
```

--------------------------------

### Initialize Terminal with TermwizBackend

Source: https://docs.rs/ratatui/latest/ratatui/backend/struct.TermwizBackend.html

Example showing how to initialize a Terminal using the TermwizBackend. This setup automatically enables raw mode and switches to the alternate screen.

```rust
use ratatui::Terminal;
use ratatui::backend::TermwizBackend;

let backend = TermwizBackend::new()?;
let mut terminal = Terminal::new(backend)?;

terminal.clear()?;
terminal.draw(|frame| {
    // -- snip --
})?;
```

--------------------------------

### Example

Source: https://docs.rs/ratatui/latest/ratatui/backend/struct.TermionBackend.html?search=std%3A%3Avec

Example of creating a TermionBackend and using it with Terminal.

```rust
use std::io::{stderr, stdout};

use ratatui::Terminal;
use ratatui::backend::TermionBackend;
use ratatui::termion::raw::IntoRawMode;

let backend = TermionBackend::new(stdout());
let mut terminal = Terminal::new(backend)?;

// Enable raw mode and alternate screen
let _raw_mode = stdout().into_raw_mode()?;
// ... draw with terminal.draw(...)

// When terminal is dropped, it will restore the screen
```

--------------------------------

### Start variant examples with Percentage, Length, Fixed, and Max constraints

Source: https://docs.rs/ratatui/latest/ratatui/prelude/layout/enum.Flex.html?search=std%3A%3Avec

Three ASCII diagrams showing items aligned to the start of the container. The first shows Percentage(20), Length(20), and Fixed(20) with excess space after them. The second shows two Max(20) constraints with excess space after. The third shows a single Max(20) with excess space after.

```text
<------------------------------------80 px------------------------------------->
┌────16 px─────┐┌──────20 px───────┐┌──────20 px───────┐
│Percentage(20)││    Length(20)    ││     Fixed(20)    │
└──────────────┘└──────────────────┘└──────────────────┘
```

```text
<------------------------------------80 px------------------------------------->
┌──────20 px───────┐┌──────20 px───────┐
│      Max(20)     ││      Max(20)     │
└──────────────────┘└──────────────────┘
```

```text
<------------------------------------80 px------------------------------------->
┌──────20 px───────┐
│      Max(20)     │
└──────────────────┘
```

--------------------------------

### Example

Source: https://docs.rs/ratatui/latest/ratatui/prelude/struct.TerminaBackend.html?search=std%3A%3Avec

Example of creating a Terminal with TerminaBackend and drawing to it.

```rust
use ratatui::Terminal;
use ratatui::backend::TerminaBackend;

let backend = TerminaBackend::new(terminal);
let mut terminal = Terminal::new(backend)?;
terminal.draw(|frame| {
    // -- snip --
})?;
```

--------------------------------

### Legacy Flex Examples

Source: https://docs.rs/ratatui/latest/ratatui/layout/enum.Flex.html

Visual examples of layout allocation under Legacy mode.

```text
<------------------------------------80 px------------------------------------->
┌──────────────────────────60 px───────────────────────────┐┌──────20 px───────┐
│                          Min(20)                         ││      Max(20)     │
└──────────────────────────────────────────────────────────┘└──────────────────┘

<------------------------------------80 px------------------------------------->
┌────────────────────────────────────80 px─────────────────────────────────────┐
│                                    Max(20)                                   │
└──────────────────────────────────────────────────────────────────────────────┘
```

--------------------------------

### Render WidgetRef Example

Source: https://docs.rs/ratatui/latest/ratatui/widgets/trait.FrameExt.html

Example showing how to render a widget using the render_widget_ref method.

```rust
use ratatui::layout::Rect;
use ratatui::widgets::{Block, FrameExt};

let block = Block::new();
let area = Rect::new(0, 0, 5, 5);
frame.render_widget_ref(&block, area);
```

--------------------------------

### no_std compatible widget using ratatui_core

Source: https://docs.rs/ratatui/latest/src/ratatui/widgets.rs.html?search=u32+-%3E+bool

Complete example of a no_std compatible widget. Add the `#![no_std]` attribute at the top of your `lib.rs`, use `core::` instead of `std::`, add `extern crate alloc;`, and use `alloc::` for heap-allocated types like `String`, `Vec`, and `Box`. This widget depends on `ratatui_core` and implements the `Widget` trait for `&MyWidget`.

```rust
#![no_std]

extern crate alloc;

use alloc::string::String;

use ratatui_core::buffer::Buffer;
use ratatui_core::layout::Rect;
use ratatui_core::text::Line;
use ratatui_core::widgets::Widget;

struct MyWidget {
    content: String,
}

impl Widget for &MyWidget {
    fn render(self, area: Rect, buf: &mut Buffer) {
        Line::raw(&self.content).render(area, buf);
    }
}

```

--------------------------------

### Getting ListItem Height

Source: https://docs.rs/ratatui/latest/ratatui/widgets/struct.ListItem.html?search=std%3A%3Avec

Examples for getting the height of a one-line and a two-line item.

```rust
use ratatui::widgets::ListItem;

let item = ListItem::new("Item 1");
assert_eq!(item.height(), 1);

```

```rust
use ratatui::widgets::ListItem;

let item = ListItem::new("Multi-line\nitem");
assert_eq!(item.height(), 2);

```

--------------------------------

### Getting ListItem Width

Source: https://docs.rs/ratatui/latest/ratatui/widgets/struct.ListItem.html?search=std%3A%3Avec

Examples for getting the max width of a single-line and a multi-line item.

```rust
use ratatui::widgets::ListItem;

let item = ListItem::new("12345");
assert_eq!(item.width(), 5);

```

```rust
use ratatui::widgets::ListItem;

let item = ListItem::new("12345\n1234567");
assert_eq!(item.width(), 7);

```

--------------------------------

### Full example with init/restore

Source: https://docs.rs/ratatui/latest/src/ratatui/init.rs.html?search=std%3A%3Avec

Shows the typical way to set up a terminal using `ratatui::init()`, run the app, and restore the terminal with `ratatui::restore()`. The panic hook automatically restores the terminal state on panics, but manual restore is recommended when the closure is complete.

```rust
use ratatui::{
    crossterm::event::{self, Event, KeyCode, KeyEventKind},
    widgets::Widget,
};

fn main() -> std::io::Result<()> {
    let mut terminal = ratatui::init();
    let result = app(&mut terminal);
    ratatui::restore();
    result
}

fn app(terminal: &mut ratatui::DefaultTerminal) -> std::io::Result<()> {
    loop {
        terminal.draw(|frame| {
            let greeting = "Hello Ratatui!";
            frame.render_widget(greeting, frame.area());
        })?;

        if let Event::Key(key) = event::read()? {
            if key.kind == KeyEventKind::Press
                && key.code == KeyCode::Char('q')
            {
                break;
            }
        }
    }
    Ok(())
}
```

--------------------------------

### List Items

Source: https://docs.rs/ratatui/latest/ratatui/widgets/struct.Bar.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example of a GET endpoint for retrieving items.

```APIDOC
## [GET] /api/v1/items

### Description
Retrieves a list of items.

### Method
GET

### Endpoint
/api/v1/items

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of items to return.
- **offset** (integer) - Optional - Number of items to skip.

```

--------------------------------

### Initialize TermionBackend with Terminal

Source: https://docs.rs/ratatui/latest/ratatui/backend/struct.TermionBackend.html

Demonstrates how to set up a terminal using TermionBackend with raw mode and alternate screen enabled.

```rust
use std::io::{stderr, stdout};

use ratatui::Terminal;
use ratatui::backend::TermionBackend;
use ratatui::termion::raw::IntoRawMode;
use ratatui::termion::screen::IntoAlternateScreen;

let writer = stdout().into_raw_mode()?.into_alternate_screen()?;
let mut backend = TermionBackend::new(writer);
// or
let writer = stderr().into_raw_mode()?.into_alternate_screen()?;
let backend = TermionBackend::new(stderr());
let mut terminal = Terminal::new(backend)?;

terminal.clear()?;
terminal.draw(|frame| {
    // -- snip --
})?;
```

--------------------------------

### Get terminal size with Backend

Source: https://docs.rs/ratatui/latest/ratatui/backend/trait.Backend.html?search=u32+-%3E+bool

Get the terminal size and assert it equals `Size::new(80, 25)`. The example imports `Backend` from `ratatui::backend` and `Size` from `ratatui::layout`. The `?` operator propagates errors from the backend.

```rust
use ratatui::{backend::Backend, layout::Size};

assert_eq!(backend.size()?, Size::new(80, 25));
```

--------------------------------

### Example: Initialize terminal with Viewport::Inline

Source: https://docs.rs/ratatui/latest/ratatui/fn.init_with_options.html?search=u32+-%3E+bool

Example usage of init_with_options with a TerminalOptions struct specifying a Viewport::Inline of 5 lines. This initializes the terminal with raw mode enabled and a panic hook installed, but does not enter the alternate screen buffer.

```rust
use ratatui::{TerminalOptions, Viewport};

let options = TerminalOptions {
    viewport: Viewport::Inline(5),
};
let terminal = ratatui::init_with_options(options);
```

--------------------------------

### offset - Get first displayed item index

Source: https://docs.rs/ratatui/latest/ratatui/widgets/struct.ListState.html?search=u32+-%3E+bool

Returns the index of the first item to be displayed. The example asserts that the default offset is 0.

```rust
use ratatui::widgets::ListState;

let state = ListState::default();
assert_eq!(state.offset(), 0);
```

--------------------------------

### Initializing and Running a Ratatui Application

Source: https://docs.rs/ratatui/latest/ratatui

Two examples showing how to initialize and run a Ratatui application: one using the `run()` convenience function and one using `init()`/`restore()` for more control.

```rust
fn main() -> std::io::Result<()> {
    ratatui::run(|mut terminal| {
        loop {
            terminal.draw(render)?;
            if should_quit()? {
                break Ok(());
            }
        }
    })
}

fn render(frame: &mut ratatui::Frame) {
    // ...
}

fn should_quit() -> std::io::Result<bool> {
    // ...
}
```

```rust
fn main() -> std::io::Result<()> {
    let mut terminal = ratatui::init();
    let result = run_app(&mut terminal);
    ratatui::restore();
    result
}

fn run_app(terminal: &mut ratatui::DefaultTerminal) -> std::io::Result<()> {
    loop {
        // ...
    }
}
```

--------------------------------

### Ratatui Initialization Examples

Source: https://docs.rs/ratatui/latest/src/ratatui/init.rs.html?search=u32+-%3E+bool

Code examples demonstrating the use of ratatui initialization functions: init, try_init, restore, try_restore, and init_with_options with inline viewport.

```rust
// Using init() - panics on failure
let mut terminal = ratatui::init();
// ... app logic ...
ratatui::restore();

// Using try_init() - returns Result for custom error handling
let mut terminal = ratatui::try_init();
// ... app logic ...
ratatui::try_restore()?;

```

```rust
use crossterm::event::{self, Event, KeyCode, KeyEventKind};
use ratatui::widgets::Widget;
use ratatui::{TerminalOptions, Viewport};

let options = TerminalOptions {
    viewport: Viewport::Inline(10),
};
let mut terminal = ratatui::init_with_options(options)?;

loop {
    terminal.draw(|frame| {
        frame.render_widget("Inline UI lives below earlier terminal output", frame.area());
    })?;
}

```

--------------------------------

### selected - Get selected item index

Source: https://docs.rs/ratatui/latest/ratatui/widgets/struct.ListState.html?search=u32+-%3E+bool

Returns the index of the selected item, or None if no item is selected. The example asserts that the default selected is None.

```rust
use ratatui::widgets::ListState;

let state = ListState::default();
assert_eq!(state.selected(), None);
```

--------------------------------

### Example: Using ratatui::run

Source: https://docs.rs/ratatui/latest/ratatui/prelude/struct.Terminal.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example of using the ratatui::run helper to set up a terminal and run an event loop.

```rust
ratatui::run(|terminal| {
    let mut should_quit = false;
    while !should_quit {
        terminal.draw(|frame| {
            frame.render_widget("Hello, World!", frame.area());
        })?;

        // Handle events, update application state, and set `should_quit = true` to exit.
    }
    Ok(())
})?;
```

--------------------------------

### Create a Dataset with custom configuration

Source: https://docs.rs/ratatui/latest/ratatui/widgets/struct.Dataset.html

This example demonstrates how to initialize a Dataset, set its name, provide data points, choose a marker type, set the graph type, and apply a red style.

```rust
use ratatui::style::Stylize;
use ratatui::symbols::Marker;
use ratatui::widgets::{Dataset, GraphType};

let dataset = Dataset::default()
    .name("dataset 1")
    .data(&[(1., 1.), (5., 5.)])
    .marker(Marker::Braille)
    .graph_type(GraphType::Line)
    .red();
```

--------------------------------

### Initialize terminal with ratatui::init

Source: https://docs.rs/ratatui/latest/ratatui/fn.init.html?search=std%3A%3Avec

Example usage of ratatui::init to create a DefaultTerminal with reasonable defaults. Call this after installing any other panic hooks so the terminal is restored before those hooks run.

```rust
let terminal = ratatui::init();
```

--------------------------------

### Buffer struct definition and usage example

Source: https://docs.rs/ratatui/latest/ratatui/buffer/struct.Buffer.html?search=std%3A%3Avec

The struct definition shows the public fields of Buffer. The example demonstrates creating a Buffer with Buffer::empty, indexing by Position and tuple, using cell_mut and cell to get Option results, and set_string with style. It also shows how to borrow a cell to avoid moving out of the buffer.

```rust
pub struct Buffer {
    pub area: Rect,
    pub content: Vec<Cell>,
}
```

```rust
use ratatui_core::buffer::{Buffer, Cell};
use ratatui_core::layout::{Position, Rect};
use ratatui_core::style::{Color, Style};

let mut buf = Buffer::empty(Rect {
    x: 0,
    y: 0,
    width: 10,
    height: 5,
});

// indexing using Position
buf[Position { x: 0, y: 0 }].set_symbol("A");
assert_eq!(buf[Position { x: 0, y: 0 }].symbol(), "A");

// indexing using (x, y) tuple (which is converted to Position)
buf[(0, 1)].set_symbol("B");
assert_eq!(buf[(0, 1)].symbol(), "B");

// getting an Option instead of panicking if the position is outside the buffer
let cell = buf
    .cell_mut(Position { x: 0, y: 2 })
    .ok_or("cell not found")?;
cell.set_symbol("C");

let cell = buf.cell(Position { x: 0, y: 2 }).ok_or("cell not found")?;
assert_eq!(cell.symbol(), "C");

buf.set_string(
    3,
    0,
    "string",
    Style::default().fg(Color::Red).bg(Color::White),
);
let cell = &buf[(5, 0)]; // cannot move out of buf, so we borrow it
assert_eq!(cell.symbol(), "r");
assert_eq!(cell.fg, Color::Red);
assert_eq!(cell.bg, Color::White);
```

--------------------------------

### Create and configure a Chart

Source: https://docs.rs/ratatui/latest/ratatui/widgets/struct.Chart.html

Example showing how to define datasets, configure axes, and assemble them into a Chart widget.

```rust
use ratatui::style::{Style, Stylize};
use ratatui::symbols;
use ratatui::widgets::{Axis, Block, Chart, Dataset, GraphType};

// Create the datasets to fill the chart with
let datasets = vec![
    // Scatter chart
    Dataset::default()
        .name("data1")
        .marker(symbols::Marker::Dot)
        .graph_type(GraphType::Scatter)
        .style(Style::default().cyan())
        .data(&[(0.0, 5.0), (1.0, 6.0), (1.5, 6.434)]),
    // Line chart
    Dataset::default()
        .name("data2")
        .marker(symbols::Marker::Braille)
        .graph_type(GraphType::Line)
        .style(Style::default().magenta())
        .data(&[(4.0, 5.0), (5.0, 8.0), (7.66, 13.5)]),
];

// Create the X axis and define its properties
let x_axis = Axis::default()
    .title("X Axis".red())
    .style(Style::default().white())
    .bounds([0.0, 10.0])
    .labels(["0.0", "5.0", "10.0"]);

// Create the Y axis and define its properties
let y_axis = Axis::default()
    .title("Y Axis".red())
    .style(Style::default().white())
    .bounds([0.0, 10.0])
    .labels(["0.0", "5.0", "10.0"]);

// Create the chart and link all the parts together
let chart = Chart::new(datasets)
    .block(Block::new().title("Chart"))
    .x_axis(x_axis)
    .y_axis(y_axis);
```

--------------------------------

### Rust code for layout with Constraint and Layout

Source: https://docs.rs/ratatui/latest/src/ratatui/lib.rs.html?search=std%3A%3Avec

Incomplete code block showing the start of a layout definition using Constraint and Layout. The example is cut off and does not include the rest of the layout code.

```Rust
use ratatui::Frame;
use ratatui::layout::{Constraint, Layout};
```

--------------------------------

### Size construction and usage examples

Source: https://docs.rs/ratatui/latest/ratatui/layout/struct.Size.html

Examples demonstrating how to create a Size instance using new and from, and how to calculate its area.

```rust
use ratatui_core::layout::{Rect, Size};

let size = Size::new(80, 24);
assert_eq!(size.area(), 1920);
let size = Size::from((80, 24));
let size = Size::from(Rect::new(0, 0, 80, 24));
assert_eq!(size.area(), 1920);
```

--------------------------------

### Example: Creating a Terminal with TermwizBackend

Source: https://docs.rs/ratatui/latest/ratatui/backend/struct.TermwizBackend.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to create a TermwizBackend and pair it with Terminal to run a draw loop. Uses ? to handle errors from new and Terminal::new.

```rust
use ratatui::Terminal;
use ratatui::backend::TermwizBackend;

let backend = TermwizBackend::new()?;
let mut terminal = Terminal::new(backend)?;

terminal.clear()?;
terminal.draw(|frame| {
    // -- snip --
})?;
```

--------------------------------

### Set and get cursor position with Backend

Source: https://docs.rs/ratatui/latest/ratatui/backend/trait.Backend.html?search=u32+-%3E+bool

Set the cursor position to (10, 20) and verify it with `get_cursor_position`. The example imports `Position` from `ratatui::layout`. The `?` operator propagates errors from the backend.

```rust
use ratatui::{backend::Backend, layout::Position};

backend.set_cursor_position(Position { x: 10, y: 20 })?;
assert_eq!(backend.get_cursor_position()?, Position { x: 10, y: 20 });
```

--------------------------------

### Queue command example

Source: https://docs.rs/ratatui/latest/ratatui/backend/struct.TerminaBackend.html?search=u32+-%3E+bool

Shows how to use `queue` to queue commands for later execution, which are executed when `flush` is called.

```rust
use std::io::{self, Write};
use crossterm::{QueueableCommand, style::Print};

 fn main() -> io::Result<()> {
    let mut stdout = io::stdout();

    // `Print` will executed executed when `flush` is called.
    stdout
        .queue(Print("foo 1\n".to_string()))?
        .queue(Print("foo 2".to_string()))?;

    // some other code (no execution happening here) ...

    // when calling `flush` on `stdout`, all commands will be written to the stdout and therefore executed.
    stdout.flush()?;

    Ok(())
}
```

--------------------------------

### Paragraph example with text, block, style, alignment, and wrap

Source: https://docs.rs/ratatui/latest/ratatui/widgets/struct.Paragraph.html?search=

Shows a complete Paragraph setup with a vector of lines, a bordered block with title, white-on-black style, centered alignment, and wrapping with trim enabled.

```rust
use ratatui::layout::Alignment;
use ratatui::style::{Style, Stylize};
use ratatui::text::{Line, Span};
use ratatui::widgets::{Block, Paragraph, Wrap};

let text = vec![
    Line::from(vec![
        Span::raw("First"),
        Span::styled("line", Style::new().green().italic()),
        ".".into(),
    ]),
    Line::from("Second line".red()),
    "Third line".into(),
];
Paragraph::new(text)
    .block(Block::bordered().title("Paragraph"))
    .style(Style::new().white().on_black())
    .alignment(Alignment::Center)
    .wrap(Wrap { trim: true });
```

--------------------------------

### Create and configure a Table

Source: https://docs.rs/ratatui/latest/ratatui/widgets/struct.Table.html

Demonstrates how to initialize a Table with rows and column constraints, and apply various styling and layout configurations.

```rust
use ratatui::layout::Constraint;
use ratatui::style::{Style, Stylize};
use ratatui::widgets::{Block, Row, Table};

let rows = [Row::new(vec!["Cell1", "Cell2", "Cell3"])];
// Columns widths are constrained in the same way as Layout...
let widths = [
    Constraint::Length(5),
    Constraint::Length(5),
    Constraint::Length(10),
];
let table = Table::new(rows, widths)
    // ...and they can be separated by a fixed spacing.
    .column_spacing(1)
    // You can set the style of the entire Table.
    .style(Style::new().blue())
    // It has an optional header, which is simply a Row always visible at the top.
    .header(
        Row::new(vec!["Col1", "Col2", "Col3"])
            .style(Style::new().bold())
            // To add space between the header and the rest of the rows, specify the margin
            .bottom_margin(1),
    )
    // It has an optional footer, which is simply a Row always visible at the bottom.
    .footer(Row::new(vec!["Updated on Dec 28"]))
    // As any other widget, a Table can be wrapped in a Block.
    .block(Block::new().title("Table"))
    // The selected row, column, cell and its content can also be styled.
    .row_highlight_style(Style::new().reversed())
    .column_highlight_style(Style::new().red())
    .cell_highlight_style(Style::new().blue())
    // ...and potentially show a symbol in front of the selection.
    .highlight_symbol(">>");
```

--------------------------------

### List Method Examples

Source: https://docs.rs/ratatui/latest/ratatui/widgets/struct.List.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Code examples demonstrating the usage of List methods: highlight_spacing, direction, and scroll_padding.

```rust
use ratatui::widgets::{HighlightSpacing, List};

let items = ["Item 1"];
let list = List::new(items).highlight_spacing(HighlightSpacing::Always);
```

```rust
use ratatui::widgets::{List, ListDirection};

let items = ["Item 1"];
let list = List::new(items).direction(ListDirection::BottomToTop);
```

```rust
use ratatui::widgets::List;

let items = ["Item 1"];
let list = List::new(items).scroll_padding(1);
```

--------------------------------

### CrosstermBackend usage example with terminal setup

Source: https://docs.rs/ratatui/latest/ratatui/backend/struct.CrosstermBackend.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to create a CrosstermBackend with stdout or stderr, create a Terminal, enable raw mode, enter alternate screen, clear and draw, then leave alternate screen and disable raw mode. Uses the crossterm crate.

```rust
use std::io::{stderr, stdout};

use crossterm::ExecutableCommand;
use crossterm::terminal::{
    EnterAlternateScreen, LeaveAlternateScreen, disable_raw_mode, enable_raw_mode,
};
use ratatui::Terminal;
use ratatui::backend::CrosstermBackend;

let mut backend = CrosstermBackend::new(stdout());
// or
let backend = CrosstermBackend::new(stderr());
let mut terminal = Terminal::new(backend)?;

enable_raw_mode()?;
stdout().execute(EnterAlternateScreen)?;

terminal.clear()?;
terminal.draw(|frame| {
    // -- snip --
})?;

stdout().execute(LeaveAlternateScreen)?;
disable_raw_mode()?;
```

--------------------------------

### Set flex behavior with flex()

Source: https://docs.rs/ratatui/latest/ratatui/layout/struct.Layout.html?search=u32+-%3E+bool

Sets the flex behavior of the layout. The first example aligns items to the start using Flex::Start; the second stretches items equally to fill available space using Flex::Legacy. Both use a horizontal layout with three Length(20) constraints.

```rust
use ratatui_core::layout::Constraint::*;
use ratatui_core::layout::{Flex, Layout};

let layout = Layout::horizontal([Length(20), Length(20), Length(20)]).flex(Flex::Start);
```

```rust
use ratatui_core::layout::Constraint::*;
use ratatui_core::layout::{Flex, Layout};

let layout = Layout::horizontal([Length(20), Length(20), Length(20)]).flex(Flex::Legacy);
```

--------------------------------

### Terminal Creation Examples

Source: https://docs.rs/ratatui/latest/ratatui/struct.Terminal.html?search=

Code examples for creating a Terminal instance with a backend and optional viewport options.

```APIDOC
use std::io::stdout;

use ratatui::Terminal;
use ratatui::backend::CrosstermBackend;

let backend = CrosstermBackend::new(stdout());
let _terminal = Terminal::new(backend)?;

// Optionally set up a panic hook to restore the terminal on panic.
let old_hook = std::panic::take_hook();
std::panic::set_hook(Box::new(move |info| {
    // restore terminal here
    old_hook(info);
}));
```

```APIDOC
use std::io::stdout;

use ratatui::backend::CrosstermBackend;
use ratatui::layout::Rect;
use ratatui::{Terminal, TerminalOptions, Viewport};

let backend = CrosstermBackend::new(stdout());
let viewport = Viewport::Fixed(Rect::new(0, 0, 10, 10));
let _terminal = Terminal::with_options(backend, TerminalOptions { viewport })?;
```

--------------------------------

### Frame struct code examples

Source: https://docs.rs/ratatui/latest/ratatui/struct.Frame.html?search=std%3A%3Avec

Code examples from the Frame struct documentation: the struct definition, a render_widget example, and a render_stateful_widget example.

```rust
pub struct Frame<'a> { /* private fields */ }
```

```rust
use ratatui_core::layout::Rect;

let area = Rect::new(0, 0, 5, 5);
frame.render_widget("Hello", area);
```

```rust
use ratatui_core::widgets::StatefulWidget;

struct DemoWidget;

impl StatefulWidget for DemoWidget {
    type State = bool;

    fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
        let symbol = if *state { "Y" } else { "N" };
        buf[(area.x, area.y)].set_symbol(symbol);
    }
}

let mut state = true;
let area = Rect::new(0, 0, 5, 5);
frame.render_stateful_widget(DemoWidget, area, &mut state);
```

--------------------------------

### Terminal::insert_before example output before and after

Source: https://docs.rs/ratatui/latest/ratatui/type.DefaultTerminal.html?search=std%3A%3Avec

Shows the example viewport state before and after inserting lines, as described in the documentation. The diagrams illustrate how the viewport is pushed down or scrolled as lines are added.

```text
+---------------------+
| pre-existing line 1 |
| pre-existing line 2 |
+---------------------+
|       viewport      |
+---------------------+
|                     |
|                     |
+---------------------+
```

```text
+---------------------+
| pre-existing line 1 |
| pre-existing line 2 |
|   inserted line 1   |
|   inserted line 2   |
+---------------------+
|       viewport      |
+---------------------+
```

```text
+---------------------+
| pre-existing line 2 |
|   inserted line 1   |
|   inserted line 2   |
|   inserted line 3   |
|   inserted line 4   |
+---------------------+
|       viewport      |
+---------------------+
```

--------------------------------

### ratatui::init / ratatui::try_init

Source: https://docs.rs/ratatui/latest/ratatui/init/index.html

Creates a terminal with default settings, including alternate screen and raw mode.

```APIDOC
## fn init() -> DefaultTerminal
## fn try_init() -> std::io::Result<DefaultTerminal>

### Description
Initializes a terminal with reasonable defaults. `init` panics on failure, while `try_init` returns a `Result`.
```

--------------------------------

### Examples of ratatui::run

Source: https://docs.rs/ratatui/latest/src/ratatui/init.rs.html

Two Rust examples demonstrating the use of the ratatui::run function: a simple closure-based example and a more complex example with a separate app function.

```rust
use crossterm::event;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    ratatui::run(|terminal| {
        loop {
            terminal.draw(|frame| frame.render_widget("Hello, world!", frame.area()))?;
            if event::read()?.is_key_press() {
                break Ok(());
            }
        }
    })
}
```

```rust
use crossterm::event;

type Result<T> = std::result::Result<T, Box<dyn std::error::Error>>;

fn app(terminal: &mut ratatui::DefaultTerminal) -> Result<()> {
    const GREETING: &str = "Hello, world!";
    terminal.draw(|frame| frame.render_widget(GREETING, frame.area()))?;
    loop {
        if event::read()?.is_key_press() {
            break Ok(());
        }
    }
}

fn main() -> Result<()> {
    ratatui::run(app)
}
```

--------------------------------

### Terminal struct definition and ratatui::run usage

Source: https://docs.rs/ratatui/latest/ratatui/prelude/struct.Terminal.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

The struct definition shows the generic Terminal type with a private fields block. The usage example demonstrates the recommended fullscreen application pattern using ratatui::run, which handles terminal setup and restoration. It draws a frame with a simple widget and includes a placeholder for event handling and state updates.

```rust
pub struct Terminal<B>
where
    B: Backend,
{ /* private fields */ }
```

```rust
ratatui::run(|terminal| {
    let mut should_quit = false;
    while !should_quit {
        terminal.draw(|frame| {
            frame.render_widget("Hello, World!", frame.area());
        })?;

        // Handle events, update application state, and set `should_quit = true` to exit.
    }
    Ok(())
})?;
```

--------------------------------

### Will render the following

Source: https://docs.rs/ratatui/latest/ratatui/text/struct.Text.html?search=u32+-%3E+bool

Shows the expected output of the previous example when rendered.

```text
left
  default
  default
      right
```

--------------------------------

### Initialize terminal with custom Viewport using TerminalOptions

Source: https://docs.rs/ratatui/latest/ratatui/fn.init_with_options.html?search=

Use when you need to start a terminal with a custom 'Viewport', such as an inline view of 5 lines. This function enables raw mode and installs a panic hook, but does not enter the alternate screen buffer, which you may need to enable manually. It panics if enabling raw mode or calculating the terminal size fails.

```rust
use ratatui::{TerminalOptions, Viewport};

let options = TerminalOptions {
    viewport: Viewport::Inline(5),
};
let terminal = ratatui::init_with_options(options);

```

--------------------------------

### Cell Examples

Source: https://docs.rs/ratatui/latest/ratatui/widgets/struct.Cell.html?search=

Examples of creating and styling a Cell.

```rust
use std::borrow::Cow;

use ratatui::style::Stylize;
use ratatui::text::{Line, Span, Text};
use ratatui::widgets::Cell;

Cell::from("simple string");
Cell::from(Span::from("span"));
Cell::from(Line::from(vec![
    Span::from("a vec of "),
    Span::from("hello")
]));
```

```rust
use ratatui::style::Stylize;
use ratatui::widgets::Cell;

Cell::new("Cell 1").red().italic();
```

```rust
use ratatui::style::{Style, Stylize};
use ratatui::widgets::Cell;

Cell::new("Cell 1").style(Style::new().red().italic());
```

```rust
use ratatui::widgets::{Cell, Row};

let rows = vec![
    Row::new(vec![Cell::new("12345").column_span(2)])
];
```

--------------------------------

### Rust code examples

Source: https://docs.rs/ratatui/latest/src/ratatui/init.rs.html?search=std%3A%3Avec

Two Rust code examples from the documentation: the first shows a basic Ratatui application using the `run` function, and the second demonstrates handling resize events and key presses in the event loop.

```rust
fn main() -> std::io::Result<()> {
    ratatui::run(|terminal| {
        loop {
            terminal.draw(|frame| frame.render_widget("Hello, world!", frame.area()))?;
            if crossterm::event::read()?.is_key_press() {
                break Ok(());
            }
        }
    })
}
```

```rust
use crossterm::event::{self, Event, KeyCode, KeyEventKind};

fn main() -> std::io::Result<()> {
    ratatui::run(|terminal| {
        loop {
            terminal.draw(|frame| {
                frame.render_widget("Resize the terminal or press q to quit", frame.area());
            })?;

            match event::read()? {
                Event::Resize(_, _) => {
                    // The next `draw` pass re-renders the UI at the new size.
                }
                Event::Key(key)
                    if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') =>
                {
                    break Ok(());
                }
            }
        }
    })
}
```

--------------------------------

### Thick Border Example

Source: https://docs.rs/ratatui/latest/ratatui/widgets/enum.BorderType.html?search=std%3A%3Avec

Example of a thick border.

```text
┏━━━━━━━┓
┃       ┃
┗━━━━━━━┛
```

--------------------------------

### init_with_options

Source: https://docs.rs/ratatui/latest/ratatui/init/fn.init_with_options.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Documentation for the `init_with_options` function in the ratatui crate, including its signature, parameters, return type, panic conditions, and an example.

```APIDOC
## Function: init_with_options

### Description
Initializes a terminal with the given options and reasonable defaults. This function allows the caller to specify a custom `Viewport` via the `TerminalOptions`. It creates a new `DefaultTerminal` and initializes it with the given options and the following defaults: raw mode is enabled, and a panic hook is installed that restores the terminal before panicking. Unlike `init`, this function does not enter the alternate screen buffer as this may not be desired in all cases. If you need the alternate screen buffer, you should enable it manually after calling this function. For more control over the terminal initialization, use `Terminal::with_options`. Ensure that this method is called _after_ your app installs any other panic hooks to ensure the terminal is restored before the other hooks are called. Generally, use this function instead of `try_init_with_options` to ensure that the terminal is restored correctly if any of the initialization steps fail. If you need to handle the error yourself, use `try_init_with_options` instead. See the module-level documentation for a comparison of all initialization functions and guidance on when to use each one.

### Signature
```rust
pub fn init_with_options(options: TerminalOptions) -> DefaultTerminal
```

### Availability
Available on **crate feature `crossterm`** only.

### Parameters
- **options** (`TerminalOptions`) - Required - The terminal options, including a custom `Viewport`.

### Returns
- **DefaultTerminal** - The initialized terminal.

### Panics
This function will panic if any of the following steps fail:
- Enabling raw mode
- Creating the terminal fails due to being unable to calculate the terminal size

### Examples
```rust
use ratatui::{TerminalOptions, Viewport};

let options = TerminalOptions {
    viewport: Viewport::Inline(5),
};
let terminal = ratatui::init_with_options(options);
```
```

--------------------------------

### Double Border Example

Source: https://docs.rs/ratatui/latest/ratatui/widgets/enum.BorderType.html?search=std%3A%3Avec

Example of a double border.

```text
╔═══════╗
║       ║
╚═══════╝
```

--------------------------------

### init

Source: https://docs.rs/ratatui/latest/ratatui/init/index.html?search=u32+-%3E+bool

Creates a terminal with reasonable defaults including alternate screen and raw mode. Panics on failure.

```APIDOC
## init

### Description
Creates a terminal with reasonable defaults including alternate screen and raw mode. Panics on failure.

### Function Signature
```rust
pub fn init() -> DefaultTerminal
```

### Return Value
- `DefaultTerminal` - A type alias for `Terminal<CrosstermBackend<Stdout>>`.

### Behavior
- Sets up the terminal with alternate screen mode and raw mode.
- Panics if initialization fails.

### Example
```rust
let mut terminal = ratatui::init();
// ... app logic ...
ratatui::restore();
```
```

--------------------------------

### Rounded Border Example

Source: https://docs.rs/ratatui/latest/ratatui/widgets/enum.BorderType.html?search=std%3A%3Avec

Example of a rounded border.

```text
╭───────╮
│       │
╰───────╯
```
Tokens:
Raw