Struct Frame 

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

A consistent view into the terminal state for rendering a single frame.

You usually get a Frame from the closure argument of Terminal::draw / Terminal::try_draw. For manual rendering, use Terminal::get_frame.

A Frame is used to render widgets into Ratatui’s current buffer and request the cursor state for the end of the render pass.

The changes drawn to the frame are applied only to the current Buffer. After the closure returns, the current buffer is compared to the previous buffer and only the changed cells are sent to the backend. This avoids drawing redundant cells.

Implementations

impl Frame<'_>

pub const fn area(&self) -> Rect

Returns the area of the current frame.

This is guaranteed not to change during rendering, so may be called multiple times.

If your app listens for a resize event from the backend, ignore that event’s dimensions for calculations performed during the current render callback and use this value instead. It is the area of the buffer that is actually being rendered for this pass.

pub const fn size(&self) -> Rect

👎Deprecated:

use area() instead

Returns the area of the current frame.

This is guaranteed not to change during rendering, so may be called multiple times.

If your app listens for a resize event from the backend, ignore that event’s dimensions for calculations performed during the current render callback and use this value instead. It is the area of the buffer that is actually being rendered for this pass.

pub fn render_widget<W>(&mut self, widget: W, area: Rect)

where W: Widget,

Render a Widget to the current buffer using Widget::render.

Usually the area argument is the size of the current frame or a sub-area of the current frame (which can be obtained using Layout to split the total area).

Rendering writes directly into the current frame buffer. If multiple widgets cover the same cells, later renders win for those cells.

Example

use ratatui_core::layout::Rect;

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

pub fn render_stateful_widget<W>( &mut self, widget: W, area: Rect, state: &mut <W as StatefulWidget>::State, )

where W: StatefulWidget,

Render a StatefulWidget to the current buffer using StatefulWidget::render.

Usually the area argument is the size of the current frame or a sub-area of the current frame (which can be obtained using Layout to split the total area).

The last argument should be an instance of the StatefulWidget::State associated to the given StatefulWidget.

Like Frame::render_widget, this writes directly into the current frame buffer. The widget owns how it interprets and mutates the provided state.

Example

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);

pub fn set_cursor_position<P>(&mut self, position: P)

where P: Into<Position>,

After this frame is rendered, make the cursor visible and put it at the specified (x, y) coordinates. If this method is not called, the cursor will be hidden.

The cursor is applied after Ratatui flushes the frame’s buffer diff to the backend.

Note that this will interfere with calls to Terminal::hide_cursor, Terminal::show_cursor, and Terminal::set_cursor_position. Pick one of the APIs and stick with it.

pub fn set_cursor(&mut self, x: u16, y: u16)

👎Deprecated:

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

After this frame is rendered, make the cursor visible and put it at the specified (x, y) coordinates. If this method is not called, the cursor will be hidden.

Note that this will interfere with calls to Terminal::hide_cursor, Terminal::show_cursor, and Terminal::set_cursor_position. Pick one of the APIs and stick with it.

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

Gets the buffer that this Frame draws into as a mutable reference.

This is an escape hatch for direct buffer manipulation. Normal applications should prefer the widget rendering methods so layout and rendering intent stay visible at the call site.

Use this when tests, custom widgets, or specialized integrations need direct cell access during a render pass.

Changes written here are not visible on the backend until the render pass is applied by Terminal::flush or a full Terminal::draw / Terminal::try_draw pass.

Example

frame.buffer_mut()[(0, 0)].set_symbol("h");

pub const fn count(&self) -> usize

Returns the current frame count.

This method provides access to the frame count, which is a sequence number indicating how many frames have been rendered up to (but not including) this one. It can be used for purposes such as animation, performance tracking, or debugging.

Each time a frame has been rendered, this count is incremented, providing a consistent way to reference the order and number of frames processed by the terminal. When count reaches its maximum value (usize::MAX), it wraps around to zero.

This count is particularly useful when dealing with dynamic content or animations where the state of the display changes over time. By tracking the frame count, developers can synchronize updates or changes to the content with the rendering process.

Examples

let current_count = frame.count();
println!("Current frame count: {}", current_count);

Trait Implementations

impl<'a> Debug for Frame<'a>

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

Formats the value using the given formatter.

impl FrameExt for Frame<'_>

Available on crate feature unstable-widget-ref only.

fn render_widget_ref<W: WidgetRef>(&mut self, widget: W, area: Rect)

Render a WidgetRef to the current buffer using WidgetRef::render_ref.

fn render_stateful_widget_ref<W>( &mut self, widget: W, area: Rect, state: &mut W::State, )

where W: StatefulWidgetRef,

Render a StatefulWidgetRef to the current buffer using StatefulWidgetRef::render_ref.

impl<'a> Hash for Frame<'a>

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.