Struct Terminal 

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

An interface to interact and draw Frames on the user’s terminal.

This is the main entry point for Ratatui. It is responsible for drawing and maintaining the state of the buffers, cursor and viewport.

The Terminal is generic over a Backend implementation which is used to interface with the underlying terminal library. The Backend trait is implemented for three popular Rust terminal libraries: Crossterm, Termion and Termwiz. See the backend module for more information.

The Terminal struct maintains two buffers: the current and the previous. When the widgets are drawn, the changes are accumulated in the current buffer. At the end of each draw pass, the two buffers are compared, and only the changes between these buffers are written to the terminal, avoiding any redundant operations. After flushing these changes, the buffers are swapped to prepare for the next draw cycle.

The terminal also has a viewport which is the area of the terminal that is currently visible to the user. It can be either fullscreen, inline or fixed. See Viewport for more information.

Applications should detect terminal resizes and call Terminal::draw to redraw the application with the new size. This will automatically resize the internal buffers to match the new size for inline and fullscreen viewports. Fixed viewports are not resized automatically.

Initialization

For most applications, consider using the convenience functions ratatui::run(), ratatui::init(), and ratatui::restore() (available since version 0.28.1) along with the DefaultTerminal type alias instead of constructing Terminal instances manually. These functions handle the common setup and teardown tasks automatically. Manual construction using Terminal::new() or Terminal::with_options() is still supported for applications that need fine-grained control over initialization.

Examples

Using convenience functions (recommended for most applications)

// Modern approach using convenience functions
ratatui::run(|terminal| {
    terminal.draw(|frame| {
        let area = frame.area();
        frame.render_widget(Paragraph::new("Hello World!"), area);
    })?;
    Ok(())
})?;

Manual construction (for fine-grained control)

use std::io::stdout;

use ratatui::{backend::CrosstermBackend, widgets::Paragraph, Terminal};

let backend = CrosstermBackend::new(stdout());
let mut terminal = Terminal::new(backend)?;
terminal.draw(|frame| {
    let area = frame.area();
    frame.render_widget(Paragraph::new("Hello World!"), area);
})?;

Implementations

impl<B> Terminal<B>

where B: Backend,

pub fn new(backend: B) -> Result<Terminal<B>, <B as Backend>::Error>

Creates a new Terminal with the given Backend with a full screen viewport.

Note that unlike ratatui::init, this does not install a panic hook, so it is recommended to do that manually when using this function, otherwise any panic messages will be printed to the alternate screen and the terminal may be left in an unusable state.

See how to set up panic hooks and better-panic example for more information.

Example

use std::io::stdout;

use ratatui::{backend::CrosstermBackend, Terminal};

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| {
    ratatui::restore();
    old_hook(info);
}));

pub fn with_options( backend: B, options: Options, ) -> Result<Terminal<B>, <B as Backend>::Error>

Creates a new Terminal with the given Backend and TerminalOptions.

Example

use std::io::stdout;

use ratatui::{backend::CrosstermBackend, layout::Rect, 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 })?;

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

Get a Frame object which provides a consistent view into the terminal state for rendering.

Note

This exists to support more advanced use cases. Most cases should be fine using Terminal::draw.

Terminal::get_frame should be used when you need direct access to the frame buffer outside of draw closure, for example:

• Unit testing widgets
• Buffer state inspection
• Cursor manipulation
• Multiple rendering passes/Buffer Manipulation
• Custom frame lifecycle management
• Buffer exporting

Example

Getting the buffer and asserting on some cells after rendering a widget.

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

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

Gets the current buffer as a mutable reference.

pub const fn backend(&self) -> &B

Gets the backend

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

Gets the backend as a mutable reference

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

Obtains a difference between the previous and the current buffer and passes it to the current backend for drawing.

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

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

Requested area will be saved to remain consistent when rendering. This leads to a full clear of the screen.

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.

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 std::io::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.

This method will:

• autoresize the terminal if necessary
• call the render callback, passing it a Frame reference to render to
• flush the current internal state by copying the current buffer to the backend
• move the cursor to the last known position if it was set during the rendering closure
• return a CompletedFrame with the current buffer and the area of the terminal

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::{layout::Position, widgets::Paragraph};

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

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

fn render(frame: &mut ratatui::Frame) {
    frame.render_widget(Paragraph::new("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 std::io::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.

This method will:

• autoresize the terminal if necessary
• call the render callback, passing it a Frame reference to render to
• flush the current internal state by copying the current buffer to the backend
• move the cursor to the last known position if it was set during the rendering closure
• return a CompletedFrame with the current buffer and the area of the terminal

The render callback passed to try_draw can return any Result with an error type that can be converted into an std::io::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 as an std::io::Error 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::widgets::Paragraph;

// with a closure
terminal.try_draw(|frame| {
    let value: u8 = "not a number".parse().map_err(io::Error::other)?;
    let area = frame.area();
    frame.render_widget(Paragraph::new("Hello World!"), area);
    frame.set_cursor_position(Position { x: 0, y: 0 });
    io::Result::Ok(())
})?;

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

fn render(frame: &mut ratatui::Frame) -> io::Result<()> {
    let value: u8 = "not a number".parse().map_err(io::Error::other)?;
    frame.render_widget(Paragraph::new("Hello World!"), frame.area());
    Ok(())
}

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

Hides the cursor.

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

Shows the cursor.

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 is the position of the cursor after the last draw call and is returned as a tuple of (x, y) coordinates.

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 is the position of the cursor after the last draw call.

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

where P: Into<Position>,

Sets the cursor position.

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

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

pub fn swap_buffers(&mut self)

Clears the inactive buffer and swaps it with the current buffer

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

Queries the real size of the backend.

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.

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.

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::TestBackend,
    style::{Color, Style},
    text::{Line, Span},
    widgets::{Paragraph, Widget},
    Terminal,
};
terminal.insert_before(1, |buf| {
    Paragraph::new(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);
});

Trait Implementations

impl<B> Clone for Terminal<B>

where B: Clone + Backend,

fn clone(&self) -> Terminal<B>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<B> Debug for Terminal<B>

where B: Debug + Backend,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<B> Default for Terminal<B>

where B: Default + Backend,

fn default() -> Terminal<B>

Returns the “default value” for a type.

impl<B> Drop for Terminal<B>

where B: Backend,

fn drop(&mut self)

Executes the destructor for this type.

impl<B> Hash for Terminal<B>

where B: Hash + Backend,

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<B> PartialEq for Terminal<B>

where B: PartialEq + Backend,

fn eq(&self, other: &Terminal<B>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<B> Eq for Terminal<B>

where B: Eq + Backend,

impl<B> StructuralPartialEq for Terminal<B>

where B: Backend,