Struct Tui 

pub struct Tui { /* private fields */ }

Manages the terminal User Interface (TUI) lifecycle, event handling, and rendering

Implementations

impl Tui

pub fn new(cancellation_token: CancellationToken) -> Result<Self>

Constructs a new terminal ui with default settings

pub fn tick_rate(self, tick_rate: f64) -> Self

Sets the tick rate for the TUI.

The tick rate determines how frequently Event::Tick is generated.

pub fn frame_rate(self, frame_rate: f64) -> Self

Sets the frame rate for the TUI.

The frame rate determines how often Event::Render is emitted.

pub fn mouse(self, mouse: bool) -> Self

Enables or disables mouse event capture.

If true, Event::Mouse events will be emitted.

pub fn paste(self, paste: bool) -> Self

Enables or disables bracketed paste mode.

If true, Event::Paste events will be emitted.

pub fn keyboard_enhancement(self, keyboard_enhancement: bool) -> Self

Enables or disables keyboard enhancement flags.

pub async fn next_event(&mut self) -> Option<Event>

Asynchronously retrieves the next event from the event queue.

Returns None if the event channel has been closed (e.g., the event loop has stopped).

pub fn enter(&mut self) -> Result<()>

Prepares the terminal for full-screen TUI interaction and starts the event loop

pub fn enter_inline(&mut self, extra_line: bool, min_height: u16) -> Result<()>

Prepares the terminal for inline TUI interaction and starts the event loop

pub fn render<F>(&mut self, render_callback: F) -> Result<CompletedFrame<'_>>

where F: FnOnce(&mut Frame<'_>, Rect),

Renders the TUI using the provided callback function.

The callback receives a mutable reference to the Frame and the area to render in, which might not be the same as the frame area for inline TUIs.

pub fn exit(self) -> Result<()>

Restores the terminal to its original state and stops the event loop

Methods from Deref<Target = Terminal<Backend<Stdout>>>

pub fn backend(&self) -> &B

Returns a shared reference to the backend.

This is primarily useful for backend-specific inspection in tests (e.g. reading TestBackend’s buffer) or for backend-specific APIs that Ratatui does not model.

Reading from the backend does not desynchronize Ratatui, but values observed here may lag behind the current render callback because Ratatui does not apply a frame to the backend until the end of Terminal::draw / Terminal::try_draw.

pub fn backend_mut(&mut self) -> &mut B

Returns a mutable reference to the backend.

This is an advanced escape hatch. Normal applications should render through Terminal::draw / Terminal::try_draw instead of mutating the backend directly.

Use this when integrating with backend-specific APIs that Ratatui does not model, or when tests need direct control over backend state.

Mutating the backend directly can desynchronize Ratatui’s internal buffers, cursor tracking, or viewport assumptions from what’s on-screen. If you do this, call Terminal::clear or perform a full draw pass before relying on Ratatui’s view of the terminal again.

pub fn size(&self) -> Result<Size, <B as Backend>::Error>

Queries the real size of the backend.

This returns the backend’s current terminal size and does not update Ratatui’s internal viewport bookkeeping by itself. The current renderable area depends on the configured Viewport; use Frame::area inside Terminal::draw / Terminal::try_draw if you want the area you should render into for the current pass.

To make Ratatui observe backend size changes for fullscreen or inline viewports, see Terminal::autoresize.

pub fn get_frame(&mut self) -> Frame<'_>

Returns a Frame for manual rendering.

Most applications should render via Terminal::draw / Terminal::try_draw. This is an escape hatch that exposes the frame construction step used by Terminal::try_draw so tests and advanced callers can render without running the full draw pipeline.

This is primarily useful for tests, backend adapters, and specialized integrations that intentionally manage presentation themselves.

Unlike draw / try_draw, this does not call Terminal::autoresize, does not write updates to the backend, and does not apply any cursor changes. After rendering, you typically call Terminal::flush, Terminal::swap_buffers, and Backend::flush.

For the full render-pass behavior that also handles resizing, cursor updates, buffer swapping, and backend flushing, see Terminal::draw and Terminal::try_draw.

The returned Frame mutably borrows the current buffer, so it must be dropped before you can call methods like Terminal::flush. The example below uses a scope to make that explicit.

Example

use ratatui::Terminal;
use ratatui::backend::{Backend, TestBackend};

let backend = TestBackend::new(30, 5);
let mut terminal = Terminal::new(backend)?;
{
    let mut frame = terminal.get_frame();
    frame.render_widget("Hello", frame.area());
}
// When not using `draw`, present the buffer manually:
terminal.flush()?;
terminal.swap_buffers();
terminal.backend_mut().flush()?;

pub fn current_buffer_mut(&mut self) -> &mut Buffer

Gets the current buffer as a mutable reference.

This is the buffer that the next Frame will render into (see Terminal::get_frame). This is a low-level escape hatch; normal applications should render inside Terminal::draw and access the buffer through widgets, or through Frame::buffer_mut when they intentionally need direct cell access during a render pass.

Mutating this buffer does not update the backend immediately. The changes become visible only after a later Terminal::flush or full draw pass applies the diff. Because this bypasses the usual render callback structure, it is mainly useful for tests and specialized integrations that intentionally manage presentation themselves.

pub fn flush(&mut self) -> Result<(), <B as Backend>::Error>

Applies the current buffer diff to the backend’s active display surface.

This compares the current buffer with the previous buffer and passes only the changed cells to Backend::draw. It is one of the building blocks used by Terminal::draw / Terminal::try_draw.

This method does not swap buffers, does not update cursor visibility or position, and does not call Backend::flush. See Terminal::swap_buffers and Backend::flush.

Terminal::flush only reasons about Ratatui’s internal buffers. It does not know whether the backend’s display surface changed since the last render pass. For example, if you leave the alternate screen and then call Terminal::flush, Ratatui may replay a diff that was computed for the alternate screen onto the main screen. In normal applications, prefer Terminal::draw / Terminal::try_draw unless you are intentionally managing the whole render pipeline yourself.

Implementation note: when there are updates, Ratatui records the position of the last updated cell as the “last known cursor position”. Inline viewports use this to preserve the cursor’s relative position within the viewport across resizes.

pub fn swap_buffers(&mut self)

Clears the inactive buffer and swaps it with the current buffer.

This is part of the standard rendering flow (see Terminal::try_draw). If you render manually using Terminal::get_frame and Terminal::flush, call this immediately afterward so the next flush can compute diffs against the correct “previous” buffer.

pub fn clear(&mut self) -> Result<(), <B as Backend>::Error>

Clear the terminal and force a full redraw on the next draw call.

What gets cleared depends on the active Viewport:

• Viewport::Fullscreen: clears the entire terminal.
• Viewport::Fixed: clears only the viewport region.
• Viewport::Inline: clears after the viewport’s origin, leaving any content above the viewport untouched.

Current behavior: for Viewport::Inline, clearing runs from the viewport origin through the end of the visible display area, not just the viewport’s rectangle. This is an implementation detail rather than a contract; do not rely on it.

This preserves the backend’s current cursor position.

This also resets the “previous” buffer so the next Terminal::flush redraws the full viewport.

Implementation note: this uses ClearType::AfterCursor starting at the viewport origin.

pub fn hide_cursor(&mut self) -> Result<(), <B as Backend>::Error>

Hides the cursor.

When using Terminal::draw / Terminal::try_draw, prefer controlling the cursor with Frame::set_cursor_position. A later successful Terminal::draw / Terminal::try_draw call may overwrite this change.

pub fn show_cursor(&mut self) -> Result<(), <B as Backend>::Error>

Shows the cursor.

When using Terminal::draw / Terminal::try_draw, prefer controlling the cursor with Frame::set_cursor_position. A later successful Terminal::draw / Terminal::try_draw call may overwrite this change.

pub fn get_cursor(&mut self) -> Result<(u16, u16), <B as Backend>::Error>

👎Deprecated:

use get_cursor_position() instead which returns Result<Position>

Gets the current cursor position.

This queries the backend for the current cursor position and returns it as an (x, y) tuple.

pub fn set_cursor( &mut self, x: u16, y: u16, ) -> Result<(), <B as Backend>::Error>

👎Deprecated:

use set_cursor_position((x, y)) instead which takes impl Into<Position>

Sets the cursor position.

pub fn get_cursor_position(&mut self) -> Result<Position, <B as Backend>::Error>

Gets the current cursor position.

This queries the backend for the current cursor position. It is not limited to Ratatui’s last render pass, so direct backend mutations may also affect the returned value.

When using Terminal::draw / Terminal::try_draw, prefer controlling the cursor with Frame::set_cursor_position. For direct control, see Terminal::set_cursor_position.

pub fn set_cursor_position<P>( &mut self, position: P, ) -> Result<(), <B as Backend>::Error>

where P: Into<Position>,

Sets the cursor position.

This updates the backend cursor and Ratatui’s internal cursor tracking. Inline viewports use that tracking when recomputing the viewport on resize.

When using Terminal::draw / Terminal::try_draw, consider using Frame::set_cursor_position instead so the cursor is updated as part of the normal rendering flow. A later successful Terminal::draw / Terminal::try_draw call may overwrite a direct cursor move.

pub fn insert_before<F>( &mut self, height: u16, draw_fn: F, ) -> Result<(), <B as Backend>::Error>

where F: FnOnce(&mut Buffer),

Insert some content before the current inline viewport. This has no effect when the viewport is not inline.

This is intended for inline UIs that want to print output (e.g. logs or status messages) above the UI without breaking it. See Viewport::Inline for how inline viewports are anchored.

The draw_fn closure will be called to draw into a writable Buffer that is height lines tall. The content of that Buffer will then be inserted before the viewport.

When Ratatui is built with the scrolling-regions feature, this can be done without clearing and redrawing the viewport. Without scrolling-regions, Ratatui falls back to a more portable approach and clears the viewport so the next Terminal::draw / Terminal::try_draw repaints it.

If the viewport isn’t yet at the bottom of the screen, inserted lines will push it towards the bottom. Once the viewport is at the bottom of the screen, inserted lines will scroll the area of the screen above the viewport upwards.

Before:

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

After inserting 2 lines:

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

After inserting 2 more lines:

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

If more lines are inserted than there is space on the screen, then the top lines will go directly into the terminal’s scrollback buffer. At the limit, if the viewport takes up the whole screen, all lines will be inserted directly into the scrollback buffer.

Examples

Insert a single line before the current viewport

use ratatui::backend::{Backend, TestBackend};
use ratatui::layout::Position;
use ratatui::style::{Color, Style};
use ratatui::text::{Line, Span};
use ratatui::widgets::Widget;
use ratatui::{Terminal, TerminalOptions, Viewport};

let mut backend = TestBackend::new(10, 10);
// Simulate existing output above the inline UI.
backend.set_cursor_position(Position::new(0, 3))?;
let mut terminal = Terminal::with_options(
    backend,
    TerminalOptions {
        viewport: Viewport::Inline(4),
    },
)?;

terminal.insert_before(1, |buf| {
    Line::from(vec![
        Span::raw("This line will be added "),
        Span::styled("before", Style::default().fg(Color::Blue)),
        Span::raw(" the current viewport"),
    ])
    .render(buf.area, buf);
})?;

pub fn draw<F>( &mut self, render_callback: F, ) -> Result<CompletedFrame<'_>, <B as Backend>::Error>

where F: FnOnce(&mut Frame<'_>),

Draws a single frame to the terminal.

Returns a CompletedFrame if successful, otherwise a backend error (B::Error).

If the render callback passed to this method can fail, use try_draw instead.

Applications should call draw or try_draw in a loop to continuously render the terminal. These methods are the main entry points for drawing to the terminal.

The Frame passed to the render callback represents the currently configured Viewport (see Frame::area and Terminal::with_options).

Build layout relative to the Rect returned by Frame::area rather than assuming the origin is (0, 0), so the same rendering code works for fixed and inline viewports.

This method will:

• call Terminal::autoresize if necessary
• call the render callback, passing it a Frame reference to render to
• call Terminal::flush to apply the current buffer diff to the backend
• show/hide the cursor based on Frame::set_cursor_position
• call Terminal::swap_buffers to prepare for the next render pass
• call Backend::flush to flush any buffered backend output
• return a CompletedFrame with the current buffer and the area used for rendering

If any backend step fails, the error is returned immediately and later steps in the render pass are skipped.

The CompletedFrame returned by this method can be useful for debugging or testing purposes, but it is often not used in regular applications.

The render callback should fully render the entire frame when called, including areas that are unchanged from the previous frame. This is because each frame is compared to the previous frame to determine what has changed, and only the changes are written to the terminal. If the render callback does not fully render the frame, the terminal will not be in a consistent state.

Examples

use ratatui::backend::TestBackend;
use ratatui::layout::Position;
use ratatui::{Frame, Terminal};

let backend = TestBackend::new(10, 10);
let mut terminal = Terminal::new(backend)?;

// With a closure.
terminal.draw(|frame| {
    let area = frame.area();
    frame.render_widget("Hello World!", area);
    frame.set_cursor_position(Position { x: 0, y: 0 });
})?;

// Or with a function.
terminal.draw(render)?;

fn render(frame: &mut Frame<'_>) {
    frame.render_widget("Hello World!", frame.area());
}

pub fn try_draw<F, E>( &mut self, render_callback: F, ) -> Result<CompletedFrame<'_>, <B as Backend>::Error>

where F: FnOnce(&mut Frame<'_>) -> Result<(), E>, E: Into<<B as Backend>::Error>,

Tries to draw a single frame to the terminal.

Returns Result::Ok containing a CompletedFrame if successful, otherwise Result::Err containing the backend error (B::Error) that caused the failure.

This is the equivalent of Terminal::draw but the render callback is a function or closure that returns a Result instead of nothing.

Applications should call try_draw or draw in a loop to continuously render the terminal. These methods are the main entry points for drawing to the terminal.

The Frame passed to the render callback represents the currently configured Viewport (see Frame::area and Terminal::with_options).

Build layout relative to the Rect returned by Frame::area rather than assuming the origin is (0, 0), so the same rendering code works for fixed and inline viewports.

This method will:

• call Terminal::autoresize if necessary
• call the render callback, passing it a Frame reference to render to
• call Terminal::flush to apply the current buffer diff to the backend
• show/hide the cursor based on Frame::set_cursor_position
• call Terminal::swap_buffers to prepare for the next render pass
• call Backend::flush to flush any buffered backend output
• return a CompletedFrame with the current buffer and the area used for rendering

If the render callback returns an error, Ratatui leaves the backend, buffers, cursor state, and frame count unchanged.

The render callback passed to try_draw can return any Result with an error type that can be converted into B::Error using the Into trait. This makes it possible to use the ? operator to propagate errors that occur during rendering. If the render callback returns an error, the error will be returned from try_draw and the terminal will not be updated.

The CompletedFrame returned by this method can be useful for debugging or testing purposes, but it is often not used in regular applications.

The render callback should fully render the entire frame when called, including areas that are unchanged from the previous frame. This is because each frame is compared to the previous frame to determine what has changed, and only the changes are written to the terminal. If the render function does not fully render the frame, the terminal will not be in a consistent state.

Examples

use std::io;

use ratatui::backend::CrosstermBackend;
use ratatui::layout::Position;
use ratatui::{Frame, Terminal};

let backend = CrosstermBackend::new(std::io::stdout());
let mut terminal = Terminal::new(backend)?;

// With a closure that returns `Result`.
terminal.try_draw(|frame| -> io::Result<()> {
    let _value: u8 = "42".parse().map_err(io::Error::other)?;
    let area = frame.area();
    frame.render_widget("Hello World!", area);
    frame.set_cursor_position(Position { x: 0, y: 0 });
    Ok(())
})?;

// Or with a function.
terminal.try_draw(render)?;

fn render(frame: &mut Frame<'_>) -> io::Result<()> {
    frame.render_widget("Hello World!", frame.area());
    Ok(())
}

pub fn apply_buffer( &mut self, ) -> Result<CompletedFrame<'_>, <B as Backend>::Error>

A low-level function that applies and flushes the current buffer to the backend.

This calls Terminal::apply_buffer_with_cursor with None, which hides the cursor.

Examples

use std::io;

use ratatui::Terminal;
use ratatui::backend::CrosstermBackend;
use ratatui::buffer::Buffer;
use ratatui::widgets::Widget;

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

terminal.autoresize()?;

let mut custom_buffer = Buffer::default();
custom_buffer.resize(terminal.get_frame().area());
custom_buffer.reset();

"Hello World!".render(custom_buffer.area, &mut custom_buffer);

terminal.current_buffer_mut().merge(&custom_buffer);
terminal.apply_buffer()?;

pub fn apply_buffer_with_cursor( &mut self, cursor_position: Option<Position>, ) -> Result<CompletedFrame<'_>, <B as Backend>::Error>

A low-level function that applies and flushes the current buffer to the backend and re-positions the cursor. This function is useful if you need to manage your own custom draw lifecycle and buffer.

Returns Result::Ok containing a CompletedFrame if successful, otherwise Result::Err containing the backend error (B::Error) that caused the failure.

This method will:

• show/hide the cursor based on cursor_position (None will hide the cursor)
• call Terminal::swap_buffers to prepare for the next render pass
• call Backend::flush to flush any buffered backend output
• return a CompletedFrame with the current buffer and the area used for rendering

The CompletedFrame returned by this method can be useful for debugging or testing purposes, but it is often not used in regular applications.

Examples

use std::io;

use ratatui::Terminal;
use ratatui::backend::CrosstermBackend;
use ratatui::buffer::Buffer;
use ratatui::widgets::Widget;

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

terminal.autoresize()?;

let mut custom_buffer = Buffer::default();
custom_buffer.resize(terminal.get_frame().area());
custom_buffer.reset();

"Hello World!".render(custom_buffer.area, &mut custom_buffer);

terminal.current_buffer_mut().merge(&custom_buffer);
terminal.apply_buffer_with_cursor(None)?;

pub fn resize(&mut self, area: Rect) -> Result<(), <B as Backend>::Error>

Updates the Terminal so that internal buffers match the requested area.

This updates the buffer size used for rendering and triggers a full clear so the next Terminal::draw / Terminal::try_draw paints into a consistent area.

When the viewport is Viewport::Inline, the area argument is treated as the new terminal size and the viewport origin is recomputed relative to the current cursor position. Ratatui attempts to keep the cursor at the same relative row within the viewport across resizes.

See also: Terminal::autoresize (automatic resizing during Terminal::draw / Terminal::try_draw).

For Viewport::Fixed and Viewport::Fullscreen, area becomes the new viewport area. For Viewport::Inline, area is interpreted as the backend’s new terminal size and the viewport origin may move to preserve the cursor’s relative row within the inline UI.

pub fn autoresize(&mut self) -> Result<(), <B as Backend>::Error>

Queries the backend for size and resizes if it doesn’t match the previous size.

This is called automatically during Terminal::draw / Terminal::try_draw for fullscreen and inline viewports. Fixed viewports are not automatically resized.

If the size changed, this calls Terminal::resize and therefore clears the affected region before the next frame is rendered.

Trait Implementations

impl Deref for Tui

type Target = Terminal<CrosstermBackend<Stdout>>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for Tui

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Drop for Tui

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.