ratatui-image

Depending on your performance and UI requirements, choose one of the following widgets:

Image widget

• Behavior: Has a fixed size in rows/columns. If the image exceeds the pixel area of the cells, it is scaled down proportionally to "fit" once during the creation of the Protocol.
• Pros: It is stateless (immediate-mode), meaning it never blocks the rendering thread/task.
• Clipping: Use Image::allow_clipping to control what happens when the image does not fit the render area.

StatefulImage widget

• Behavior: Adapts to its render area at render-time. It can be configured to fit, crop, or scale to the available area.
• Pros: Highly flexible for dynamic layouts.
• Cons: It is stateful (requires render_stateful_widget) and the resizing/encoding process is blocking.
• Best Practice: Always offload StatefulImage operations to another thread or async task (e.g., using thread::ThreadProtocol) to keep the UI responsive.

To use ratatui-image, you need to:

1. Use a Picker to determine the terminal's font size and supported graphics protocol.
2. Load an image using the image crate.
3. Calculate the target size in character cells based on the Picker's font size.
4. Use picker.new_protocol() to transform the image data into a Protocol object (e.g., Sixels, Kitty, iTerm2, or ASCII/halfblocks).
5. Render the image using the Image widget within your Ratatui terminal.draw loop.

Note: For production apps, it is recommended to use thread::ThreadProtocol to perform image resizing and encoding in a background thread to avoid blocking the UI.

use ratatui::{backend::TestBackend, layout::Size, Terminal, Frame};
use ratatui_image::{Image, picker::Picker, protocol::Protocol, Resize};

struct App {
    // We need to hold the image data somewhere.
    image: Protocol,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let backend = TestBackend::new(80, 30);
    let mut terminal = Terminal::new(backend)?;

    // Should use `Picker::from_query_stdio()?` to get the font size and protocol,
    // but we can't put that here because that would break doctests!
    let mut picker = Picker::halfblocks();

    // Load an image with the image crate.
    let dyn_img = image::ImageReader::open("./assets/Ada.png")?.decode()?;

    let font_size = picker.font_size();
    let size = Size::new(
        dyn_img.width().div_ceil(font_size.width as u32) as u16,
        dyn_img.height().div_ceil(font_size.height as u32) as u16,
    );

    // Create the Protocol once, or in other words, transform the image data to Sixels, Kitty,
    // iTerm2 base64 PNG data, or some kind of ASCII-art.
    let image = picker.new_protocol(dyn_img, size, Resize::Fit(None))?;

    let mut app = App { image };

    // This would be your typical `loop {` in a real app:
    terminal.draw(|f| {
        let image = Image::new(&app.image);
        // Rendering the transformed data is now cheap.
        f.render_widget(image, f.area());
    });

    Ok()
}

Choosing between the two primary widgets depends on your performance and responsiveness requirements:

• Image (Stateless):

  • Has a fixed size in rows/columns.
  • Does not react to area resizes.
  • The Protocol is resized once at creation time.
  • Advantage: It is stateless in the Ratatui sense, meaning it is extremely fast and never blocks the rendering thread.
  • Clipping: If the image is larger than the render area, it won't render unless .allow_clipping(true) is called.

• StatefulImage (Stateful):

  • Adapts to the render area at render-time.
  • Can be configured to Fit, Crop, or Scale to the available area.
  • Warning: Resizing and encoding are blocking operations. If used in a reactive UI without offloading to a background thread (e.g., using thread::ThreadProtocol), it will block the UI thread.
  • Requires using f.render_stateful_widget with a mutable state parameter.

Backend Features

• crossterm (default): Use if your Ratatui backend is crossterm.
• termion: Use if your Ratatui backend is termion.
• termwiz: Available but not currently working correctly with ratatui-image.

Chafa Library (for rendering without image protocols)

Note: These features are mutually exclusive. Enable only one at a time.

• chafa-dyn (default): Dynamically link against libchafa.so. Requires libchafa at runtime.
• chafa-static: Statically link against libchafa.a. The library is embedded in the binary.
• To avoid Chafa entirely: Use --no-default-features --features image-defaults,crossterm.

Other Features

• image-defaults (default): Enables default image formats. To reduce dependencies, disable this and manually enable specific formats in your Cargo.toml.
• serde: Enables #[derive] for picker::ProtocolType to allow saving protocol information in user configurations.
• tokio: Enables tokio's UnboundedSender when using thread::ThreadProtocol.

The following table describes which graphics protocols are supported by various terminals:

Note: halfblocks (using unicode half-block characters) should work in all terminals, even if the font size cannot be detected, using a 4:8 pixel ratio.

When using ratatui-image in your own application, you can use a Picker to manage how an image is rendered and resized according to the terminal's capabilities.

To create a new resize protocol for an image, use picker.new_resize_protocol(image_source) where image_source is a DynamicImage from the image crate. This returns a StatefulProtocol which must be passed to render_stateful_widget to display the image.

Example workflow:

1. Initialize a Picker (e.g., Picker::halfblocks()).
2. Load an image using the image crate.
3. Create the state: let image_state = picker.new_resize_protocol(image_source.clone());.
4. Render using f.render_stateful_widget(StatefulImage::default(), area, &mut image_state);.

let picker = Picker::halfblocks().unwrap();
let image_source = image::ImageReader::open(&filename)?.decode()?;
let image_state = picker.new_resize_protocol(image_source.clone());

// In your draw loop:
let image = StatefulImage::default();
f.render_stateful_widget(image, area, &mut image_state);