Struct ScrollBar 

pub struct ScrollBar { /* private fields */ }

A proportional scrollbar widget with fractional thumb rendering.

Method map

Construction

• Self::new
• Self::orientation
• Self::vertical
• Self::horizontal

Position and lengths

• Self::content_len
• Self::viewport_len
• Self::offset

Appearance

• Self::track_style
• Self::thumb_style
• Self::arrow_style
• Self::glyph_set
• Self::arrows

Interaction

• Self::handle_event
• Self::handle_mouse_event, when a crossterm feature is enabled
• Self::track_click_behavior
• Self::scroll_step

Important

• content_len and viewport_len are in logical units.
• Zero values are treated as 1.
• The scrollbar renders into a single row or column.

Behavior

The thumb length is proportional to viewport_len / content_len and clamped to at least one full cell for usability. When content_len <= viewport_len, the thumb fills the track. Areas with zero width or height render nothing.

Arrow endcaps, when enabled, consume one cell at the start/end of the track. The thumb and track render in the remaining inner area. Clicking an arrow steps the offset by scroll_step.

Styling

Track glyphs use track_style. Thumb glyphs use thumb_style. Arrow endcaps use arrow_style, which defaults to white on dark gray.

Scrollbar glyphs are terminal characters. For visible track glyphs, thumb blocks, and arrow symbols, Style::fg colors the glyph itself and Style::bg colors the cell behind it. The default GlyphSet::minimal track renders spaces, so only the track background is visible in empty track cells. Visible track glyph sets, such as GlyphSet::box_drawing and GlyphSet::unicode, can use foreground color for the track line. Thumb glyphs are block characters, so Style::fg is usually the useful knob for thumb color; Style::bg still colors the rest of the cell. With partial thumb glyphs, especially on a visible line track such as GlyphSet::box_drawing, that background can show at the ends of the thumb. Match the thumb background to the track background unless that contrast is intentional.

use ratatui_core::style::{Color, Style};
use tui_scrollbar::{ScrollBar, ScrollBarArrows, ScrollLengths};

let lengths = ScrollLengths {
    content_len: 120,
    viewport_len: 30,
};
let scrollbar = ScrollBar::vertical(lengths)
    .arrows(ScrollBarArrows::Both)
    .track_style(Style::new().bg(Color::Black))
    .thumb_style(Style::new().fg(Color::Rgb(255, 158, 100)))
    .arrow_style(Style::new().fg(Color::Yellow).bg(Color::Black));

State

This widget is stateless. Pointer drag state lives in crate::ScrollBarInteraction.

Examples

Minimal rendering only needs an area, lengths, an offset, and a buffer.

use ratatui_core::buffer::Buffer;
use ratatui_core::layout::Rect;
use ratatui_core::widgets::Widget;
use tui_scrollbar::{ScrollBar, ScrollLengths};

let area = Rect::new(0, 0, 1, 5);
let lengths = ScrollLengths {
    content_len: 200,
    viewport_len: 40,
};
let scrollbar = ScrollBar::vertical(lengths).offset(60);

let mut buffer = Buffer::empty(area);
scrollbar.render(area, &mut buffer);

Updating offsets on input

This is the typical pattern for pointer handling: feed events to the scrollbar and apply the returned command to your stored offset.

use ratatui_core::layout::Rect;
use tui_scrollbar::{
    PointerButton, PointerEvent, PointerEventKind, ScrollBar, ScrollBarInteraction,
    ScrollCommand, ScrollEvent, ScrollLengths,
};

let area = Rect::new(0, 0, 1, 10);
let lengths = ScrollLengths {
    content_len: 400,
    viewport_len: 80,
};
let scrollbar = ScrollBar::vertical(lengths).offset(0);
let mut interaction = ScrollBarInteraction::new();
let mut offset = 0;

let event = ScrollEvent::Pointer(PointerEvent {
    column: 0,
    row: 3,
    kind: PointerEventKind::Down,
    button: PointerButton::Primary,
});

if let Some(ScrollCommand::SetOffset(next)) =
    scrollbar.handle_event(area, event, &mut interaction)
{
    offset = next;
}

Track click behavior

Choose between classic page jumps or jump-to-click behavior.

use tui_scrollbar::{ScrollBar, ScrollLengths, TrackClickBehavior};

let lengths = ScrollLengths {
    content_len: 10,
    viewport_len: 5,
};
let scrollbar =
    ScrollBar::vertical(lengths).track_click_behavior(TrackClickBehavior::JumpToClick);

Arrow endcaps

Arrow endcaps are optional. When enabled, they reserve one cell at each end of the track.

use tui_scrollbar::{ScrollBar, ScrollBarArrows, ScrollLengths};

let lengths = ScrollLengths {
    content_len: 120,
    viewport_len: 24,
};
let scrollbar = ScrollBar::vertical(lengths).arrows(ScrollBarArrows::Both);

Implementations

impl ScrollBar

pub fn handle_event( &self, area: Rect, event: ScrollEvent, interaction: &mut ScrollBarInteraction, ) -> Option<ScrollCommand>

Handles a backend-agnostic scrollbar event.

Returns a ScrollCommand when the event should update the caller-owned offset. This method does not mutate your application state directly.

Pointer events outside the track are ignored. Scroll wheel events are ignored unless the axis matches the scrollbar orientation.

use ratatui_core::layout::Rect;
use tui_scrollbar::{
    PointerButton, PointerEvent, PointerEventKind, ScrollBar, ScrollBarInteraction,
    ScrollEvent, ScrollLengths,
};

let area = Rect::new(0, 0, 1, 6);
let lengths = ScrollLengths {
    content_len: 120,
    viewport_len: 24,
};
let scrollbar = ScrollBar::vertical(lengths).offset(0);
let mut interaction = ScrollBarInteraction::new();
let event = ScrollEvent::Pointer(PointerEvent {
    column: 0,
    row: 2,
    kind: PointerEventKind::Down,
    button: PointerButton::Primary,
});

let _ = scrollbar.handle_event(area, event, &mut interaction);

pub fn handle_mouse_event( &self, area: Rect, event: MouseEvent, interaction: &mut ScrollBarInteraction, ) -> Option<ScrollCommand>

Handles crossterm mouse events for this scrollbar.

This helper converts crossterm events into ScrollEvent values before delegating to Self::handle_event. See the scrollbar_mouse example for a complete terminal event loop with mouse capture.

Examples found in repository

examples/scrollbar_mouse.rs (lines 270-274)

    fn handle_mouse_event(&mut self, event: event::MouseEvent) {
        let Some(layout) = self.layout else {
            return;
        };
        let (h_metrics, v_metrics) = self.metrics_for_layout(layout.content);
        let horizontal = self.horizontal_scrollbar(h_metrics);
        let vertical = self.vertical_scrollbar(v_metrics);

        if let Some(command) = horizontal.handle_mouse_event(
            layout.horizontal_bar,
            event,
            &mut self.horizontal_interaction,
        ) {
            self.apply_command(command, true);
        }
        if let Some(command) =
            vertical.handle_mouse_event(layout.vertical_bar, event, &mut self.vertical_interaction)
        {
            self.apply_command(command, false);
        }
    }

impl ScrollBar

pub fn new(orientation: ScrollBarOrientation, lengths: ScrollLengths) -> Self

Creates a scrollbar with the given orientation and lengths.

Use Self::vertical or Self::horizontal when the orientation is known at the call site.

Zero lengths are treated as 1.

use tui_scrollbar::{ScrollBar, ScrollBarOrientation, ScrollLengths};

let lengths = ScrollLengths {
    content_len: 120,
    viewport_len: 40,
};
let scrollbar = ScrollBar::new(ScrollBarOrientation::Vertical, lengths);

pub fn vertical(lengths: ScrollLengths) -> Self

Creates a vertical scrollbar with the given content and viewport lengths.

The track length is derived from the render area’s height.

use tui_scrollbar::{ScrollBar, ScrollLengths};

let lengths = ScrollLengths {
    content_len: 120,
    viewport_len: 40,
};
let scrollbar = ScrollBar::vertical(lengths);

Examples found in repository

examples/scrollbar.rs (line 170)

fn render_vertical_steps(frame: &mut ratatui::Frame, cells: Vec<Rect>) {
    for (index, area) in cells.iter().enumerate() {
        let [label_area, bar_area] = area.layout(&Layout::vertical([
            Constraint::Length(1),
            Constraint::Fill(1),
        ]));
        if bar_area.height == 0 {
            continue;
        }
        let metrics = build_metrics(bar_area.height as usize, 3);
        let (label, thumb_start) = step_entry(&metrics, index);
        let label = (label % 8).to_string();
        let offset = metrics.offset_for_thumb_start(thumb_start);
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        let scrollbar = ScrollBar::vertical(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(offset);
        render_label(frame, label_area, &label);
        frame.render_widget(&scrollbar, bar_area);
    }
}

examples/scrollbar_styled.rs (line 65)

fn render(area: Rect, frame: &mut ratatui::Frame) {
    if area.width < 2 || area.height < 2 {
        return;
    }

    let horizontal_bar = area
        .rows()
        .next_back()
        .unwrap_or(area)
        .inner(Margin::new(1, 0));
    let vertical_bar = area
        .columns()
        .next_back()
        .unwrap_or(area)
        .inner(Margin::new(0, 1));

    let block = Block::new()
        .borders(Borders::ALL)
        .title("styled scrollbars")
        .border_style((Color::LightBlue, Color::Black))
        .style((Color::Gray, Color::Black));
    let content = block.inner(area).inner(Margin::new(2, 1));
    frame.render_widget(block, area);

    frame.render_widget(
        Paragraph::new("track_style, thumb_style, and arrow_style can each use distinct colors")
            .style((Color::Gray, Color::Black)),
        content,
    );

    let lengths = ScrollLengths {
        content_len: 160,
        viewport_len: 40,
    };
    let horizontal = ScrollBar::horizontal(lengths)
        .offset(48)
        .arrows(ScrollBarArrows::Both)
        .glyph_set(GlyphSet::box_drawing())
        .track_style((Color::Blue, Color::Black).into())
        .thumb_style((Color::Yellow, Modifier::BOLD).into())
        .arrow_style((Color::LightGreen, Color::Black, Modifier::BOLD).into());
    let vertical = ScrollBar::vertical(lengths)
        .offset(80)
        .arrows(ScrollBarArrows::Both)
        .glyph_set(GlyphSet::box_drawing())
        .track_style((Color::Magenta, Color::Black).into())
        .thumb_style((Color::Cyan, Modifier::BOLD).into())
        .arrow_style((Color::LightRed, Color::Black, Modifier::BOLD).into());

    frame.render_widget(&horizontal, horizontal_bar);
    frame.render_widget(&vertical, vertical_bar);
}

examples/scrollbar_mouse.rs (line 210)

    fn render(&mut self, frame: &mut ratatui::Frame) {
        let area = frame.area();
        if area.width < 2 || area.height < 2 {
            return;
        }

        let title = "tui-scrollbar - mouse scroll demo";
        let block = Block::new()
            .borders(Borders::TOP)
            .border_style(Style::new().fg(TITLE_FG).bg(TITLE_BG))
            .style(Style::new().fg(BLOCK_FG).bg(BLOCK_BG))
            .title(
                Line::from(title)
                    .centered()
                    .fg(TITLE_FG)
                    .bg(TITLE_BG)
                    .bold(),
            );
        frame.render_widget(&block, area);

        let content_area = Rect {
            y: area.y.saturating_add(1),
            height: area.height.saturating_sub(1),
            ..area
        };
        let help = "Arrows: move | Wheel: scroll | Drag: thumb | q/Esc: quit";
        let help_area = Rect {
            x: content_area.x.saturating_add(1),
            y: content_area.y,
            width: content_area.width.saturating_sub(1),
            height: 1,
        };
        if help_area.width > 0 {
            frame.render_widget(
                Paragraph::new(help).style(Style::new().fg(TITLE_FG)),
                help_area,
            );
        }
        let content_area = Rect {
            y: content_area.y.saturating_add(1),
            height: content_area.height.saturating_sub(1),
            ..content_area
        };

        // Split out the bottom row and right column for the scrollbars.
        let [content_row, bar_row] = content_area.layout(&Layout::vertical([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [content, vertical_bar] = content_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [horizontal_bar, _corner] = bar_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));

        self.layout = Some(LayoutState {
            content,
            vertical_bar,
            horizontal_bar,
        });

        // Keep offsets valid when the terminal is resized.
        let (h_metrics, v_metrics) = self.metrics_for_layout(content);
        self.horizontal_offset = self.horizontal_offset.min(h_metrics.max_offset());
        self.vertical_offset = self.vertical_offset.min(v_metrics.max_offset());

        let horizontal_lengths = ScrollLengths {
            content_len: h_metrics.content_len(),
            viewport_len: h_metrics.viewport_len(),
        };
        let track_style = Style::new().bg(SCROLLBAR_TRACK_BG);
        let thumb_style = Style::new().fg(SCROLLBAR_THUMB_FG).bg(SCROLLBAR_THUMB_BG);
        let arrow_style = Style::new().fg(SCROLLBAR_ARROW_FG).bg(SCROLLBAR_TRACK_BG);
        let horizontal = ScrollBar::horizontal(horizontal_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);
        let vertical_lengths = ScrollLengths {
            content_len: v_metrics.content_len(),
            viewport_len: v_metrics.viewport_len(),
        };
        let vertical = ScrollBar::vertical(vertical_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.vertical_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);

        frame.render_widget(&horizontal, horizontal_bar);
        frame.render_widget(&vertical, vertical_bar);
    }

    /// Handles keyboard and mouse events, updating offsets as needed.
    fn handle_events(&mut self) -> Result<()> {
        match event::read()? {
            Event::Key(key) => {
                if key.is_press() {
                    self.handle_key_event(key.code);
                }
            }
            Event::Mouse(event) => {
                self.handle_mouse_event(event);
            }
            _ => {}
        }
        Ok(())
    }

    /// Handles keyboard input, updating offsets or exiting as needed.
    fn handle_key_event(&mut self, code: KeyCode) {
        match code {
            KeyCode::Char('q') | KeyCode::Esc => self.state = AppState::Quit,
            KeyCode::Up | KeyCode::Char('k') => self.handle_key_scroll(0, -(KEY_STEP as isize)),
            KeyCode::Down | KeyCode::Char('j') => self.handle_key_scroll(0, KEY_STEP as isize),
            KeyCode::Left | KeyCode::Char('h') => self.handle_key_scroll(-(KEY_STEP as isize), 0),
            KeyCode::Right | KeyCode::Char('l') => self.handle_key_scroll(KEY_STEP as isize, 0),
            _ => {}
        }
    }

    /// Applies a keyboard delta to the scrollbar offsets.
    fn handle_key_scroll(&mut self, dx: isize, dy: isize) {
        let Some(layout) = self.layout else {
            return;
        };
        let (h_metrics, v_metrics) = self.metrics_for_layout(layout.content);
        self.horizontal_offset =
            Self::apply_delta(self.horizontal_offset, dx, h_metrics.max_offset());
        self.vertical_offset = Self::apply_delta(self.vertical_offset, dy, v_metrics.max_offset());
    }

    /// Handles crossterm mouse events using the scrollbar helpers.
    fn handle_mouse_event(&mut self, event: event::MouseEvent) {
        let Some(layout) = self.layout else {
            return;
        };
        let (h_metrics, v_metrics) = self.metrics_for_layout(layout.content);
        let horizontal = self.horizontal_scrollbar(h_metrics);
        let vertical = self.vertical_scrollbar(v_metrics);

        if let Some(command) = horizontal.handle_mouse_event(
            layout.horizontal_bar,
            event,
            &mut self.horizontal_interaction,
        ) {
            self.apply_command(command, true);
        }
        if let Some(command) =
            vertical.handle_mouse_event(layout.vertical_bar, event, &mut self.vertical_interaction)
        {
            self.apply_command(command, false);
        }
    }

    /// Applies a scroll command to the current axis offset.
    fn apply_command(&mut self, command: ScrollCommand, is_horizontal: bool) {
        let ScrollCommand::SetOffset(offset) = command;
        if is_horizontal {
            self.horizontal_offset = offset;
        } else {
            self.vertical_offset = offset;
        }
    }

    /// Builds a horizontal scrollbar from the current metrics.
    fn horizontal_scrollbar(&self, metrics: ScrollMetrics) -> ScrollBar {
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        ScrollBar::horizontal(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
    }

    /// Builds a vertical scrollbar from the current metrics.
    fn vertical_scrollbar(&self, metrics: ScrollMetrics) -> ScrollBar {
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        ScrollBar::vertical(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.vertical_offset)
            .scroll_step(SUBCELL)
    }

pub fn horizontal(lengths: ScrollLengths) -> Self

Creates a horizontal scrollbar with the given content and viewport lengths.

The track length is derived from the render area’s width.

use tui_scrollbar::{ScrollBar, ScrollLengths};

let lengths = ScrollLengths {
    content_len: 120,
    viewport_len: 40,
};
let scrollbar = ScrollBar::horizontal(lengths);

Examples found in repository

examples/scrollbar.rs (line 144)

fn render_horizontal_steps(frame: &mut ratatui::Frame, cells: Vec<Rect>) {
    for (index, area) in cells.iter().enumerate() {
        let [label_area, bar_area] = area.layout(&Layout::horizontal([
            Constraint::Length(2),
            Constraint::Fill(1),
        ]));
        if bar_area.width == 0 {
            continue;
        }
        let metrics = build_metrics(bar_area.width as usize, 6);
        let (label, thumb_start) = step_entry(&metrics, index);
        let label = (label % 8).to_string();
        let offset = metrics.offset_for_thumb_start(thumb_start);
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        let scrollbar = ScrollBar::horizontal(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(offset);
        render_label(frame, label_area, &label);
        frame.render_widget(&scrollbar, bar_area);
    }
}

examples/scrollbar_styled.rs (line 58)

fn render(area: Rect, frame: &mut ratatui::Frame) {
    if area.width < 2 || area.height < 2 {
        return;
    }

    let horizontal_bar = area
        .rows()
        .next_back()
        .unwrap_or(area)
        .inner(Margin::new(1, 0));
    let vertical_bar = area
        .columns()
        .next_back()
        .unwrap_or(area)
        .inner(Margin::new(0, 1));

    let block = Block::new()
        .borders(Borders::ALL)
        .title("styled scrollbars")
        .border_style((Color::LightBlue, Color::Black))
        .style((Color::Gray, Color::Black));
    let content = block.inner(area).inner(Margin::new(2, 1));
    frame.render_widget(block, area);

    frame.render_widget(
        Paragraph::new("track_style, thumb_style, and arrow_style can each use distinct colors")
            .style((Color::Gray, Color::Black)),
        content,
    );

    let lengths = ScrollLengths {
        content_len: 160,
        viewport_len: 40,
    };
    let horizontal = ScrollBar::horizontal(lengths)
        .offset(48)
        .arrows(ScrollBarArrows::Both)
        .glyph_set(GlyphSet::box_drawing())
        .track_style((Color::Blue, Color::Black).into())
        .thumb_style((Color::Yellow, Modifier::BOLD).into())
        .arrow_style((Color::LightGreen, Color::Black, Modifier::BOLD).into());
    let vertical = ScrollBar::vertical(lengths)
        .offset(80)
        .arrows(ScrollBarArrows::Both)
        .glyph_set(GlyphSet::box_drawing())
        .track_style((Color::Magenta, Color::Black).into())
        .thumb_style((Color::Cyan, Modifier::BOLD).into())
        .arrow_style((Color::LightRed, Color::Black, Modifier::BOLD).into());

    frame.render_widget(&horizontal, horizontal_bar);
    frame.render_widget(&vertical, vertical_bar);
}

examples/scrollbar_mouse.rs (line 199)

    fn render(&mut self, frame: &mut ratatui::Frame) {
        let area = frame.area();
        if area.width < 2 || area.height < 2 {
            return;
        }

        let title = "tui-scrollbar - mouse scroll demo";
        let block = Block::new()
            .borders(Borders::TOP)
            .border_style(Style::new().fg(TITLE_FG).bg(TITLE_BG))
            .style(Style::new().fg(BLOCK_FG).bg(BLOCK_BG))
            .title(
                Line::from(title)
                    .centered()
                    .fg(TITLE_FG)
                    .bg(TITLE_BG)
                    .bold(),
            );
        frame.render_widget(&block, area);

        let content_area = Rect {
            y: area.y.saturating_add(1),
            height: area.height.saturating_sub(1),
            ..area
        };
        let help = "Arrows: move | Wheel: scroll | Drag: thumb | q/Esc: quit";
        let help_area = Rect {
            x: content_area.x.saturating_add(1),
            y: content_area.y,
            width: content_area.width.saturating_sub(1),
            height: 1,
        };
        if help_area.width > 0 {
            frame.render_widget(
                Paragraph::new(help).style(Style::new().fg(TITLE_FG)),
                help_area,
            );
        }
        let content_area = Rect {
            y: content_area.y.saturating_add(1),
            height: content_area.height.saturating_sub(1),
            ..content_area
        };

        // Split out the bottom row and right column for the scrollbars.
        let [content_row, bar_row] = content_area.layout(&Layout::vertical([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [content, vertical_bar] = content_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [horizontal_bar, _corner] = bar_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));

        self.layout = Some(LayoutState {
            content,
            vertical_bar,
            horizontal_bar,
        });

        // Keep offsets valid when the terminal is resized.
        let (h_metrics, v_metrics) = self.metrics_for_layout(content);
        self.horizontal_offset = self.horizontal_offset.min(h_metrics.max_offset());
        self.vertical_offset = self.vertical_offset.min(v_metrics.max_offset());

        let horizontal_lengths = ScrollLengths {
            content_len: h_metrics.content_len(),
            viewport_len: h_metrics.viewport_len(),
        };
        let track_style = Style::new().bg(SCROLLBAR_TRACK_BG);
        let thumb_style = Style::new().fg(SCROLLBAR_THUMB_FG).bg(SCROLLBAR_THUMB_BG);
        let arrow_style = Style::new().fg(SCROLLBAR_ARROW_FG).bg(SCROLLBAR_TRACK_BG);
        let horizontal = ScrollBar::horizontal(horizontal_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);
        let vertical_lengths = ScrollLengths {
            content_len: v_metrics.content_len(),
            viewport_len: v_metrics.viewport_len(),
        };
        let vertical = ScrollBar::vertical(vertical_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.vertical_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);

        frame.render_widget(&horizontal, horizontal_bar);
        frame.render_widget(&vertical, vertical_bar);
    }

    /// Handles keyboard and mouse events, updating offsets as needed.
    fn handle_events(&mut self) -> Result<()> {
        match event::read()? {
            Event::Key(key) => {
                if key.is_press() {
                    self.handle_key_event(key.code);
                }
            }
            Event::Mouse(event) => {
                self.handle_mouse_event(event);
            }
            _ => {}
        }
        Ok(())
    }

    /// Handles keyboard input, updating offsets or exiting as needed.
    fn handle_key_event(&mut self, code: KeyCode) {
        match code {
            KeyCode::Char('q') | KeyCode::Esc => self.state = AppState::Quit,
            KeyCode::Up | KeyCode::Char('k') => self.handle_key_scroll(0, -(KEY_STEP as isize)),
            KeyCode::Down | KeyCode::Char('j') => self.handle_key_scroll(0, KEY_STEP as isize),
            KeyCode::Left | KeyCode::Char('h') => self.handle_key_scroll(-(KEY_STEP as isize), 0),
            KeyCode::Right | KeyCode::Char('l') => self.handle_key_scroll(KEY_STEP as isize, 0),
            _ => {}
        }
    }

    /// Applies a keyboard delta to the scrollbar offsets.
    fn handle_key_scroll(&mut self, dx: isize, dy: isize) {
        let Some(layout) = self.layout else {
            return;
        };
        let (h_metrics, v_metrics) = self.metrics_for_layout(layout.content);
        self.horizontal_offset =
            Self::apply_delta(self.horizontal_offset, dx, h_metrics.max_offset());
        self.vertical_offset = Self::apply_delta(self.vertical_offset, dy, v_metrics.max_offset());
    }

    /// Handles crossterm mouse events using the scrollbar helpers.
    fn handle_mouse_event(&mut self, event: event::MouseEvent) {
        let Some(layout) = self.layout else {
            return;
        };
        let (h_metrics, v_metrics) = self.metrics_for_layout(layout.content);
        let horizontal = self.horizontal_scrollbar(h_metrics);
        let vertical = self.vertical_scrollbar(v_metrics);

        if let Some(command) = horizontal.handle_mouse_event(
            layout.horizontal_bar,
            event,
            &mut self.horizontal_interaction,
        ) {
            self.apply_command(command, true);
        }
        if let Some(command) =
            vertical.handle_mouse_event(layout.vertical_bar, event, &mut self.vertical_interaction)
        {
            self.apply_command(command, false);
        }
    }

    /// Applies a scroll command to the current axis offset.
    fn apply_command(&mut self, command: ScrollCommand, is_horizontal: bool) {
        let ScrollCommand::SetOffset(offset) = command;
        if is_horizontal {
            self.horizontal_offset = offset;
        } else {
            self.vertical_offset = offset;
        }
    }

    /// Builds a horizontal scrollbar from the current metrics.
    fn horizontal_scrollbar(&self, metrics: ScrollMetrics) -> ScrollBar {
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        ScrollBar::horizontal(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
    }

pub const fn orientation(self, orientation: ScrollBarOrientation) -> Self

Sets the scrollbar orientation.

This is mostly useful when sharing a builder chain and choosing the orientation later.

use tui_scrollbar::{ScrollBar, ScrollBarOrientation, ScrollLengths};

let lengths = ScrollLengths {
    content_len: 120,
    viewport_len: 40,
};
let scrollbar = ScrollBar::vertical(lengths).orientation(ScrollBarOrientation::Horizontal);

pub const fn content_len(self, content_len: usize) -> Self

Sets the total scrollable content length in logical units.

Larger values shrink the thumb, while smaller values enlarge it.

Zero values are treated as 1.

use tui_scrollbar::{ScrollBar, ScrollLengths};

let lengths = ScrollLengths {
    content_len: 120,
    viewport_len: 40,
};
let scrollbar = ScrollBar::vertical(lengths).content_len(240);

pub const fn viewport_len(self, viewport_len: usize) -> Self

Sets the visible viewport length in logical units.

When viewport_len >= content_len, the thumb fills the track.

Zero values are treated as 1.

use tui_scrollbar::{ScrollBar, ScrollLengths};

let lengths = ScrollLengths {
    content_len: 120,
    viewport_len: 40,
};
let scrollbar = ScrollBar::vertical(lengths).viewport_len(60);

pub const fn offset(self, offset: usize) -> Self

Sets the current scroll offset in logical units.

Offsets are clamped to content_len - viewport_len during rendering and input handling, not when this builder is called.

use tui_scrollbar::{ScrollBar, ScrollLengths};

let lengths = ScrollLengths {
    content_len: 120,
    viewport_len: 40,
};
let scrollbar = ScrollBar::vertical(lengths).offset(30);

Examples found in repository

examples/scrollbar.rs (line 146)

fn render_horizontal_steps(frame: &mut ratatui::Frame, cells: Vec<Rect>) {
    for (index, area) in cells.iter().enumerate() {
        let [label_area, bar_area] = area.layout(&Layout::horizontal([
            Constraint::Length(2),
            Constraint::Fill(1),
        ]));
        if bar_area.width == 0 {
            continue;
        }
        let metrics = build_metrics(bar_area.width as usize, 6);
        let (label, thumb_start) = step_entry(&metrics, index);
        let label = (label % 8).to_string();
        let offset = metrics.offset_for_thumb_start(thumb_start);
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        let scrollbar = ScrollBar::horizontal(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(offset);
        render_label(frame, label_area, &label);
        frame.render_widget(&scrollbar, bar_area);
    }
}

/// Draws vertical scrollbars that sweep every 1/8th thumb position, left to right.
fn render_vertical_steps(frame: &mut ratatui::Frame, cells: Vec<Rect>) {
    for (index, area) in cells.iter().enumerate() {
        let [label_area, bar_area] = area.layout(&Layout::vertical([
            Constraint::Length(1),
            Constraint::Fill(1),
        ]));
        if bar_area.height == 0 {
            continue;
        }
        let metrics = build_metrics(bar_area.height as usize, 3);
        let (label, thumb_start) = step_entry(&metrics, index);
        let label = (label % 8).to_string();
        let offset = metrics.offset_for_thumb_start(thumb_start);
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        let scrollbar = ScrollBar::vertical(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(offset);
        render_label(frame, label_area, &label);
        frame.render_widget(&scrollbar, bar_area);
    }
}

examples/scrollbar_styled.rs (line 59)

fn render(area: Rect, frame: &mut ratatui::Frame) {
    if area.width < 2 || area.height < 2 {
        return;
    }

    let horizontal_bar = area
        .rows()
        .next_back()
        .unwrap_or(area)
        .inner(Margin::new(1, 0));
    let vertical_bar = area
        .columns()
        .next_back()
        .unwrap_or(area)
        .inner(Margin::new(0, 1));

    let block = Block::new()
        .borders(Borders::ALL)
        .title("styled scrollbars")
        .border_style((Color::LightBlue, Color::Black))
        .style((Color::Gray, Color::Black));
    let content = block.inner(area).inner(Margin::new(2, 1));
    frame.render_widget(block, area);

    frame.render_widget(
        Paragraph::new("track_style, thumb_style, and arrow_style can each use distinct colors")
            .style((Color::Gray, Color::Black)),
        content,
    );

    let lengths = ScrollLengths {
        content_len: 160,
        viewport_len: 40,
    };
    let horizontal = ScrollBar::horizontal(lengths)
        .offset(48)
        .arrows(ScrollBarArrows::Both)
        .glyph_set(GlyphSet::box_drawing())
        .track_style((Color::Blue, Color::Black).into())
        .thumb_style((Color::Yellow, Modifier::BOLD).into())
        .arrow_style((Color::LightGreen, Color::Black, Modifier::BOLD).into());
    let vertical = ScrollBar::vertical(lengths)
        .offset(80)
        .arrows(ScrollBarArrows::Both)
        .glyph_set(GlyphSet::box_drawing())
        .track_style((Color::Magenta, Color::Black).into())
        .thumb_style((Color::Cyan, Modifier::BOLD).into())
        .arrow_style((Color::LightRed, Color::Black, Modifier::BOLD).into());

    frame.render_widget(&horizontal, horizontal_bar);
    frame.render_widget(&vertical, vertical_bar);
}

examples/scrollbar_mouse.rs (line 201)

    fn render(&mut self, frame: &mut ratatui::Frame) {
        let area = frame.area();
        if area.width < 2 || area.height < 2 {
            return;
        }

        let title = "tui-scrollbar - mouse scroll demo";
        let block = Block::new()
            .borders(Borders::TOP)
            .border_style(Style::new().fg(TITLE_FG).bg(TITLE_BG))
            .style(Style::new().fg(BLOCK_FG).bg(BLOCK_BG))
            .title(
                Line::from(title)
                    .centered()
                    .fg(TITLE_FG)
                    .bg(TITLE_BG)
                    .bold(),
            );
        frame.render_widget(&block, area);

        let content_area = Rect {
            y: area.y.saturating_add(1),
            height: area.height.saturating_sub(1),
            ..area
        };
        let help = "Arrows: move | Wheel: scroll | Drag: thumb | q/Esc: quit";
        let help_area = Rect {
            x: content_area.x.saturating_add(1),
            y: content_area.y,
            width: content_area.width.saturating_sub(1),
            height: 1,
        };
        if help_area.width > 0 {
            frame.render_widget(
                Paragraph::new(help).style(Style::new().fg(TITLE_FG)),
                help_area,
            );
        }
        let content_area = Rect {
            y: content_area.y.saturating_add(1),
            height: content_area.height.saturating_sub(1),
            ..content_area
        };

        // Split out the bottom row and right column for the scrollbars.
        let [content_row, bar_row] = content_area.layout(&Layout::vertical([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [content, vertical_bar] = content_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [horizontal_bar, _corner] = bar_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));

        self.layout = Some(LayoutState {
            content,
            vertical_bar,
            horizontal_bar,
        });

        // Keep offsets valid when the terminal is resized.
        let (h_metrics, v_metrics) = self.metrics_for_layout(content);
        self.horizontal_offset = self.horizontal_offset.min(h_metrics.max_offset());
        self.vertical_offset = self.vertical_offset.min(v_metrics.max_offset());

        let horizontal_lengths = ScrollLengths {
            content_len: h_metrics.content_len(),
            viewport_len: h_metrics.viewport_len(),
        };
        let track_style = Style::new().bg(SCROLLBAR_TRACK_BG);
        let thumb_style = Style::new().fg(SCROLLBAR_THUMB_FG).bg(SCROLLBAR_THUMB_BG);
        let arrow_style = Style::new().fg(SCROLLBAR_ARROW_FG).bg(SCROLLBAR_TRACK_BG);
        let horizontal = ScrollBar::horizontal(horizontal_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);
        let vertical_lengths = ScrollLengths {
            content_len: v_metrics.content_len(),
            viewport_len: v_metrics.viewport_len(),
        };
        let vertical = ScrollBar::vertical(vertical_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.vertical_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);

        frame.render_widget(&horizontal, horizontal_bar);
        frame.render_widget(&vertical, vertical_bar);
    }

    /// Handles keyboard and mouse events, updating offsets as needed.
    fn handle_events(&mut self) -> Result<()> {
        match event::read()? {
            Event::Key(key) => {
                if key.is_press() {
                    self.handle_key_event(key.code);
                }
            }
            Event::Mouse(event) => {
                self.handle_mouse_event(event);
            }
            _ => {}
        }
        Ok(())
    }

    /// Handles keyboard input, updating offsets or exiting as needed.
    fn handle_key_event(&mut self, code: KeyCode) {
        match code {
            KeyCode::Char('q') | KeyCode::Esc => self.state = AppState::Quit,
            KeyCode::Up | KeyCode::Char('k') => self.handle_key_scroll(0, -(KEY_STEP as isize)),
            KeyCode::Down | KeyCode::Char('j') => self.handle_key_scroll(0, KEY_STEP as isize),
            KeyCode::Left | KeyCode::Char('h') => self.handle_key_scroll(-(KEY_STEP as isize), 0),
            KeyCode::Right | KeyCode::Char('l') => self.handle_key_scroll(KEY_STEP as isize, 0),
            _ => {}
        }
    }

    /// Applies a keyboard delta to the scrollbar offsets.
    fn handle_key_scroll(&mut self, dx: isize, dy: isize) {
        let Some(layout) = self.layout else {
            return;
        };
        let (h_metrics, v_metrics) = self.metrics_for_layout(layout.content);
        self.horizontal_offset =
            Self::apply_delta(self.horizontal_offset, dx, h_metrics.max_offset());
        self.vertical_offset = Self::apply_delta(self.vertical_offset, dy, v_metrics.max_offset());
    }

    /// Handles crossterm mouse events using the scrollbar helpers.
    fn handle_mouse_event(&mut self, event: event::MouseEvent) {
        let Some(layout) = self.layout else {
            return;
        };
        let (h_metrics, v_metrics) = self.metrics_for_layout(layout.content);
        let horizontal = self.horizontal_scrollbar(h_metrics);
        let vertical = self.vertical_scrollbar(v_metrics);

        if let Some(command) = horizontal.handle_mouse_event(
            layout.horizontal_bar,
            event,
            &mut self.horizontal_interaction,
        ) {
            self.apply_command(command, true);
        }
        if let Some(command) =
            vertical.handle_mouse_event(layout.vertical_bar, event, &mut self.vertical_interaction)
        {
            self.apply_command(command, false);
        }
    }

    /// Applies a scroll command to the current axis offset.
    fn apply_command(&mut self, command: ScrollCommand, is_horizontal: bool) {
        let ScrollCommand::SetOffset(offset) = command;
        if is_horizontal {
            self.horizontal_offset = offset;
        } else {
            self.vertical_offset = offset;
        }
    }

    /// Builds a horizontal scrollbar from the current metrics.
    fn horizontal_scrollbar(&self, metrics: ScrollMetrics) -> ScrollBar {
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        ScrollBar::horizontal(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
    }

    /// Builds a vertical scrollbar from the current metrics.
    fn vertical_scrollbar(&self, metrics: ScrollMetrics) -> ScrollBar {
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        ScrollBar::vertical(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.vertical_offset)
            .scroll_step(SUBCELL)
    }

pub const fn track_style(self, style: Style) -> Self

Sets the style applied to track glyphs.

Track styling applies only to cells where the thumb is not rendered.

use ratatui_core::style::{Color, Style};
use tui_scrollbar::{ScrollBar, ScrollLengths};

let lengths = ScrollLengths {
    content_len: 120,
    viewport_len: 40,
};
let scrollbar = ScrollBar::vertical(lengths).track_style(Style::new().bg(Color::Black));

Examples found in repository

examples/scrollbar_styled.rs (line 62)

fn render(area: Rect, frame: &mut ratatui::Frame) {
    if area.width < 2 || area.height < 2 {
        return;
    }

    let horizontal_bar = area
        .rows()
        .next_back()
        .unwrap_or(area)
        .inner(Margin::new(1, 0));
    let vertical_bar = area
        .columns()
        .next_back()
        .unwrap_or(area)
        .inner(Margin::new(0, 1));

    let block = Block::new()
        .borders(Borders::ALL)
        .title("styled scrollbars")
        .border_style((Color::LightBlue, Color::Black))
        .style((Color::Gray, Color::Black));
    let content = block.inner(area).inner(Margin::new(2, 1));
    frame.render_widget(block, area);

    frame.render_widget(
        Paragraph::new("track_style, thumb_style, and arrow_style can each use distinct colors")
            .style((Color::Gray, Color::Black)),
        content,
    );

    let lengths = ScrollLengths {
        content_len: 160,
        viewport_len: 40,
    };
    let horizontal = ScrollBar::horizontal(lengths)
        .offset(48)
        .arrows(ScrollBarArrows::Both)
        .glyph_set(GlyphSet::box_drawing())
        .track_style((Color::Blue, Color::Black).into())
        .thumb_style((Color::Yellow, Modifier::BOLD).into())
        .arrow_style((Color::LightGreen, Color::Black, Modifier::BOLD).into());
    let vertical = ScrollBar::vertical(lengths)
        .offset(80)
        .arrows(ScrollBarArrows::Both)
        .glyph_set(GlyphSet::box_drawing())
        .track_style((Color::Magenta, Color::Black).into())
        .thumb_style((Color::Cyan, Modifier::BOLD).into())
        .arrow_style((Color::LightRed, Color::Black, Modifier::BOLD).into());

    frame.render_widget(&horizontal, horizontal_bar);
    frame.render_widget(&vertical, vertical_bar);
}

examples/scrollbar_mouse.rs (line 203)

    fn render(&mut self, frame: &mut ratatui::Frame) {
        let area = frame.area();
        if area.width < 2 || area.height < 2 {
            return;
        }

        let title = "tui-scrollbar - mouse scroll demo";
        let block = Block::new()
            .borders(Borders::TOP)
            .border_style(Style::new().fg(TITLE_FG).bg(TITLE_BG))
            .style(Style::new().fg(BLOCK_FG).bg(BLOCK_BG))
            .title(
                Line::from(title)
                    .centered()
                    .fg(TITLE_FG)
                    .bg(TITLE_BG)
                    .bold(),
            );
        frame.render_widget(&block, area);

        let content_area = Rect {
            y: area.y.saturating_add(1),
            height: area.height.saturating_sub(1),
            ..area
        };
        let help = "Arrows: move | Wheel: scroll | Drag: thumb | q/Esc: quit";
        let help_area = Rect {
            x: content_area.x.saturating_add(1),
            y: content_area.y,
            width: content_area.width.saturating_sub(1),
            height: 1,
        };
        if help_area.width > 0 {
            frame.render_widget(
                Paragraph::new(help).style(Style::new().fg(TITLE_FG)),
                help_area,
            );
        }
        let content_area = Rect {
            y: content_area.y.saturating_add(1),
            height: content_area.height.saturating_sub(1),
            ..content_area
        };

        // Split out the bottom row and right column for the scrollbars.
        let [content_row, bar_row] = content_area.layout(&Layout::vertical([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [content, vertical_bar] = content_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [horizontal_bar, _corner] = bar_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));

        self.layout = Some(LayoutState {
            content,
            vertical_bar,
            horizontal_bar,
        });

        // Keep offsets valid when the terminal is resized.
        let (h_metrics, v_metrics) = self.metrics_for_layout(content);
        self.horizontal_offset = self.horizontal_offset.min(h_metrics.max_offset());
        self.vertical_offset = self.vertical_offset.min(v_metrics.max_offset());

        let horizontal_lengths = ScrollLengths {
            content_len: h_metrics.content_len(),
            viewport_len: h_metrics.viewport_len(),
        };
        let track_style = Style::new().bg(SCROLLBAR_TRACK_BG);
        let thumb_style = Style::new().fg(SCROLLBAR_THUMB_FG).bg(SCROLLBAR_THUMB_BG);
        let arrow_style = Style::new().fg(SCROLLBAR_ARROW_FG).bg(SCROLLBAR_TRACK_BG);
        let horizontal = ScrollBar::horizontal(horizontal_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);
        let vertical_lengths = ScrollLengths {
            content_len: v_metrics.content_len(),
            viewport_len: v_metrics.viewport_len(),
        };
        let vertical = ScrollBar::vertical(vertical_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.vertical_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);

        frame.render_widget(&horizontal, horizontal_bar);
        frame.render_widget(&vertical, vertical_bar);
    }

pub const fn thumb_style(self, style: Style) -> Self

Sets the style applied to thumb glyphs.

Thumb styling applies to full and partial thumb cells. Thumb glyphs are block characters, so Style::fg usually controls the visible thumb color. Use Style::bg only when the cell behind the glyph should differ from the track. On partial thumb cells, the background can show at the thumb ends.

use ratatui_core::style::{Color, Style};
use tui_scrollbar::{ScrollBar, ScrollLengths};

let lengths = ScrollLengths {
    content_len: 120,
    viewport_len: 40,
};
let scrollbar =
    ScrollBar::vertical(lengths).thumb_style(Style::new().fg(Color::Rgb(255, 158, 100)));

Examples found in repository

examples/scrollbar_styled.rs (line 63)

fn render(area: Rect, frame: &mut ratatui::Frame) {
    if area.width < 2 || area.height < 2 {
        return;
    }

    let horizontal_bar = area
        .rows()
        .next_back()
        .unwrap_or(area)
        .inner(Margin::new(1, 0));
    let vertical_bar = area
        .columns()
        .next_back()
        .unwrap_or(area)
        .inner(Margin::new(0, 1));

    let block = Block::new()
        .borders(Borders::ALL)
        .title("styled scrollbars")
        .border_style((Color::LightBlue, Color::Black))
        .style((Color::Gray, Color::Black));
    let content = block.inner(area).inner(Margin::new(2, 1));
    frame.render_widget(block, area);

    frame.render_widget(
        Paragraph::new("track_style, thumb_style, and arrow_style can each use distinct colors")
            .style((Color::Gray, Color::Black)),
        content,
    );

    let lengths = ScrollLengths {
        content_len: 160,
        viewport_len: 40,
    };
    let horizontal = ScrollBar::horizontal(lengths)
        .offset(48)
        .arrows(ScrollBarArrows::Both)
        .glyph_set(GlyphSet::box_drawing())
        .track_style((Color::Blue, Color::Black).into())
        .thumb_style((Color::Yellow, Modifier::BOLD).into())
        .arrow_style((Color::LightGreen, Color::Black, Modifier::BOLD).into());
    let vertical = ScrollBar::vertical(lengths)
        .offset(80)
        .arrows(ScrollBarArrows::Both)
        .glyph_set(GlyphSet::box_drawing())
        .track_style((Color::Magenta, Color::Black).into())
        .thumb_style((Color::Cyan, Modifier::BOLD).into())
        .arrow_style((Color::LightRed, Color::Black, Modifier::BOLD).into());

    frame.render_widget(&horizontal, horizontal_bar);
    frame.render_widget(&vertical, vertical_bar);
}

examples/scrollbar_mouse.rs (line 204)

    fn render(&mut self, frame: &mut ratatui::Frame) {
        let area = frame.area();
        if area.width < 2 || area.height < 2 {
            return;
        }

        let title = "tui-scrollbar - mouse scroll demo";
        let block = Block::new()
            .borders(Borders::TOP)
            .border_style(Style::new().fg(TITLE_FG).bg(TITLE_BG))
            .style(Style::new().fg(BLOCK_FG).bg(BLOCK_BG))
            .title(
                Line::from(title)
                    .centered()
                    .fg(TITLE_FG)
                    .bg(TITLE_BG)
                    .bold(),
            );
        frame.render_widget(&block, area);

        let content_area = Rect {
            y: area.y.saturating_add(1),
            height: area.height.saturating_sub(1),
            ..area
        };
        let help = "Arrows: move | Wheel: scroll | Drag: thumb | q/Esc: quit";
        let help_area = Rect {
            x: content_area.x.saturating_add(1),
            y: content_area.y,
            width: content_area.width.saturating_sub(1),
            height: 1,
        };
        if help_area.width > 0 {
            frame.render_widget(
                Paragraph::new(help).style(Style::new().fg(TITLE_FG)),
                help_area,
            );
        }
        let content_area = Rect {
            y: content_area.y.saturating_add(1),
            height: content_area.height.saturating_sub(1),
            ..content_area
        };

        // Split out the bottom row and right column for the scrollbars.
        let [content_row, bar_row] = content_area.layout(&Layout::vertical([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [content, vertical_bar] = content_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [horizontal_bar, _corner] = bar_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));

        self.layout = Some(LayoutState {
            content,
            vertical_bar,
            horizontal_bar,
        });

        // Keep offsets valid when the terminal is resized.
        let (h_metrics, v_metrics) = self.metrics_for_layout(content);
        self.horizontal_offset = self.horizontal_offset.min(h_metrics.max_offset());
        self.vertical_offset = self.vertical_offset.min(v_metrics.max_offset());

        let horizontal_lengths = ScrollLengths {
            content_len: h_metrics.content_len(),
            viewport_len: h_metrics.viewport_len(),
        };
        let track_style = Style::new().bg(SCROLLBAR_TRACK_BG);
        let thumb_style = Style::new().fg(SCROLLBAR_THUMB_FG).bg(SCROLLBAR_THUMB_BG);
        let arrow_style = Style::new().fg(SCROLLBAR_ARROW_FG).bg(SCROLLBAR_TRACK_BG);
        let horizontal = ScrollBar::horizontal(horizontal_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);
        let vertical_lengths = ScrollLengths {
            content_len: v_metrics.content_len(),
            viewport_len: v_metrics.viewport_len(),
        };
        let vertical = ScrollBar::vertical(vertical_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.vertical_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);

        frame.render_widget(&horizontal, horizontal_bar);
        frame.render_widget(&vertical, vertical_bar);
    }

pub const fn arrow_style(self, style: Style) -> Self

Sets the style applied to arrow glyphs.

Arrow endcaps render only when enabled with Self::arrows. If no arrow style is configured internally, arrows fall back to the track style.

use ratatui_core::style::{Color, Style};
use tui_scrollbar::{ScrollBar, ScrollBarArrows, ScrollLengths};

let lengths = ScrollLengths {
    content_len: 120,
    viewport_len: 40,
};
let scrollbar = ScrollBar::vertical(lengths)
    .arrows(ScrollBarArrows::Both)
    .arrow_style(Style::new().fg(Color::Yellow).bg(Color::Black));

Examples found in repository

examples/scrollbar_styled.rs (line 64)

fn render(area: Rect, frame: &mut ratatui::Frame) {
    if area.width < 2 || area.height < 2 {
        return;
    }

    let horizontal_bar = area
        .rows()
        .next_back()
        .unwrap_or(area)
        .inner(Margin::new(1, 0));
    let vertical_bar = area
        .columns()
        .next_back()
        .unwrap_or(area)
        .inner(Margin::new(0, 1));

    let block = Block::new()
        .borders(Borders::ALL)
        .title("styled scrollbars")
        .border_style((Color::LightBlue, Color::Black))
        .style((Color::Gray, Color::Black));
    let content = block.inner(area).inner(Margin::new(2, 1));
    frame.render_widget(block, area);

    frame.render_widget(
        Paragraph::new("track_style, thumb_style, and arrow_style can each use distinct colors")
            .style((Color::Gray, Color::Black)),
        content,
    );

    let lengths = ScrollLengths {
        content_len: 160,
        viewport_len: 40,
    };
    let horizontal = ScrollBar::horizontal(lengths)
        .offset(48)
        .arrows(ScrollBarArrows::Both)
        .glyph_set(GlyphSet::box_drawing())
        .track_style((Color::Blue, Color::Black).into())
        .thumb_style((Color::Yellow, Modifier::BOLD).into())
        .arrow_style((Color::LightGreen, Color::Black, Modifier::BOLD).into());
    let vertical = ScrollBar::vertical(lengths)
        .offset(80)
        .arrows(ScrollBarArrows::Both)
        .glyph_set(GlyphSet::box_drawing())
        .track_style((Color::Magenta, Color::Black).into())
        .thumb_style((Color::Cyan, Modifier::BOLD).into())
        .arrow_style((Color::LightRed, Color::Black, Modifier::BOLD).into());

    frame.render_widget(&horizontal, horizontal_bar);
    frame.render_widget(&vertical, vertical_bar);
}

examples/scrollbar_mouse.rs (line 205)

    fn render(&mut self, frame: &mut ratatui::Frame) {
        let area = frame.area();
        if area.width < 2 || area.height < 2 {
            return;
        }

        let title = "tui-scrollbar - mouse scroll demo";
        let block = Block::new()
            .borders(Borders::TOP)
            .border_style(Style::new().fg(TITLE_FG).bg(TITLE_BG))
            .style(Style::new().fg(BLOCK_FG).bg(BLOCK_BG))
            .title(
                Line::from(title)
                    .centered()
                    .fg(TITLE_FG)
                    .bg(TITLE_BG)
                    .bold(),
            );
        frame.render_widget(&block, area);

        let content_area = Rect {
            y: area.y.saturating_add(1),
            height: area.height.saturating_sub(1),
            ..area
        };
        let help = "Arrows: move | Wheel: scroll | Drag: thumb | q/Esc: quit";
        let help_area = Rect {
            x: content_area.x.saturating_add(1),
            y: content_area.y,
            width: content_area.width.saturating_sub(1),
            height: 1,
        };
        if help_area.width > 0 {
            frame.render_widget(
                Paragraph::new(help).style(Style::new().fg(TITLE_FG)),
                help_area,
            );
        }
        let content_area = Rect {
            y: content_area.y.saturating_add(1),
            height: content_area.height.saturating_sub(1),
            ..content_area
        };

        // Split out the bottom row and right column for the scrollbars.
        let [content_row, bar_row] = content_area.layout(&Layout::vertical([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [content, vertical_bar] = content_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [horizontal_bar, _corner] = bar_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));

        self.layout = Some(LayoutState {
            content,
            vertical_bar,
            horizontal_bar,
        });

        // Keep offsets valid when the terminal is resized.
        let (h_metrics, v_metrics) = self.metrics_for_layout(content);
        self.horizontal_offset = self.horizontal_offset.min(h_metrics.max_offset());
        self.vertical_offset = self.vertical_offset.min(v_metrics.max_offset());

        let horizontal_lengths = ScrollLengths {
            content_len: h_metrics.content_len(),
            viewport_len: h_metrics.viewport_len(),
        };
        let track_style = Style::new().bg(SCROLLBAR_TRACK_BG);
        let thumb_style = Style::new().fg(SCROLLBAR_THUMB_FG).bg(SCROLLBAR_THUMB_BG);
        let arrow_style = Style::new().fg(SCROLLBAR_ARROW_FG).bg(SCROLLBAR_TRACK_BG);
        let horizontal = ScrollBar::horizontal(horizontal_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);
        let vertical_lengths = ScrollLengths {
            content_len: v_metrics.content_len(),
            viewport_len: v_metrics.viewport_len(),
        };
        let vertical = ScrollBar::vertical(vertical_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.vertical_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);

        frame.render_widget(&horizontal, horizontal_bar);
        frame.render_widget(&vertical, vertical_bar);
    }

pub const fn glyph_set(self, glyph_set: GlyphSet) -> Self

Selects the glyph set used to render the track and thumb.

GlyphSet::symbols_for_legacy_computing uses Symbols for Legacy Computing for 1/8th upper/right fills. Use GlyphSet::unicode if you want to avoid the legacy supplement, or GlyphSet::box_drawing when you want a visible line track.

use tui_scrollbar::{GlyphSet, ScrollBar, ScrollLengths};

let lengths = ScrollLengths {
    content_len: 120,
    viewport_len: 40,
};
let scrollbar = ScrollBar::vertical(lengths).glyph_set(GlyphSet::unicode());

Examples found in repository

examples/scrollbar_styled.rs (line 61)

fn render(area: Rect, frame: &mut ratatui::Frame) {
    if area.width < 2 || area.height < 2 {
        return;
    }

    let horizontal_bar = area
        .rows()
        .next_back()
        .unwrap_or(area)
        .inner(Margin::new(1, 0));
    let vertical_bar = area
        .columns()
        .next_back()
        .unwrap_or(area)
        .inner(Margin::new(0, 1));

    let block = Block::new()
        .borders(Borders::ALL)
        .title("styled scrollbars")
        .border_style((Color::LightBlue, Color::Black))
        .style((Color::Gray, Color::Black));
    let content = block.inner(area).inner(Margin::new(2, 1));
    frame.render_widget(block, area);

    frame.render_widget(
        Paragraph::new("track_style, thumb_style, and arrow_style can each use distinct colors")
            .style((Color::Gray, Color::Black)),
        content,
    );

    let lengths = ScrollLengths {
        content_len: 160,
        viewport_len: 40,
    };
    let horizontal = ScrollBar::horizontal(lengths)
        .offset(48)
        .arrows(ScrollBarArrows::Both)
        .glyph_set(GlyphSet::box_drawing())
        .track_style((Color::Blue, Color::Black).into())
        .thumb_style((Color::Yellow, Modifier::BOLD).into())
        .arrow_style((Color::LightGreen, Color::Black, Modifier::BOLD).into());
    let vertical = ScrollBar::vertical(lengths)
        .offset(80)
        .arrows(ScrollBarArrows::Both)
        .glyph_set(GlyphSet::box_drawing())
        .track_style((Color::Magenta, Color::Black).into())
        .thumb_style((Color::Cyan, Modifier::BOLD).into())
        .arrow_style((Color::LightRed, Color::Black, Modifier::BOLD).into());

    frame.render_widget(&horizontal, horizontal_bar);
    frame.render_widget(&vertical, vertical_bar);
}

pub const fn arrows(self, arrows: ScrollBarArrows) -> Self

Sets which arrow endcaps are rendered.

Each enabled arrow reserves one cell at the start or end of the track.

use tui_scrollbar::{ScrollBar, ScrollBarArrows, ScrollLengths};

let lengths = ScrollLengths {
    content_len: 120,
    viewport_len: 40,
};
let scrollbar = ScrollBar::vertical(lengths).arrows(ScrollBarArrows::Both);

Examples found in repository

examples/scrollbar.rs (line 145)

fn render_horizontal_steps(frame: &mut ratatui::Frame, cells: Vec<Rect>) {
    for (index, area) in cells.iter().enumerate() {
        let [label_area, bar_area] = area.layout(&Layout::horizontal([
            Constraint::Length(2),
            Constraint::Fill(1),
        ]));
        if bar_area.width == 0 {
            continue;
        }
        let metrics = build_metrics(bar_area.width as usize, 6);
        let (label, thumb_start) = step_entry(&metrics, index);
        let label = (label % 8).to_string();
        let offset = metrics.offset_for_thumb_start(thumb_start);
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        let scrollbar = ScrollBar::horizontal(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(offset);
        render_label(frame, label_area, &label);
        frame.render_widget(&scrollbar, bar_area);
    }
}

/// Draws vertical scrollbars that sweep every 1/8th thumb position, left to right.
fn render_vertical_steps(frame: &mut ratatui::Frame, cells: Vec<Rect>) {
    for (index, area) in cells.iter().enumerate() {
        let [label_area, bar_area] = area.layout(&Layout::vertical([
            Constraint::Length(1),
            Constraint::Fill(1),
        ]));
        if bar_area.height == 0 {
            continue;
        }
        let metrics = build_metrics(bar_area.height as usize, 3);
        let (label, thumb_start) = step_entry(&metrics, index);
        let label = (label % 8).to_string();
        let offset = metrics.offset_for_thumb_start(thumb_start);
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        let scrollbar = ScrollBar::vertical(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(offset);
        render_label(frame, label_area, &label);
        frame.render_widget(&scrollbar, bar_area);
    }
}

examples/scrollbar_styled.rs (line 60)

fn render(area: Rect, frame: &mut ratatui::Frame) {
    if area.width < 2 || area.height < 2 {
        return;
    }

    let horizontal_bar = area
        .rows()
        .next_back()
        .unwrap_or(area)
        .inner(Margin::new(1, 0));
    let vertical_bar = area
        .columns()
        .next_back()
        .unwrap_or(area)
        .inner(Margin::new(0, 1));

    let block = Block::new()
        .borders(Borders::ALL)
        .title("styled scrollbars")
        .border_style((Color::LightBlue, Color::Black))
        .style((Color::Gray, Color::Black));
    let content = block.inner(area).inner(Margin::new(2, 1));
    frame.render_widget(block, area);

    frame.render_widget(
        Paragraph::new("track_style, thumb_style, and arrow_style can each use distinct colors")
            .style((Color::Gray, Color::Black)),
        content,
    );

    let lengths = ScrollLengths {
        content_len: 160,
        viewport_len: 40,
    };
    let horizontal = ScrollBar::horizontal(lengths)
        .offset(48)
        .arrows(ScrollBarArrows::Both)
        .glyph_set(GlyphSet::box_drawing())
        .track_style((Color::Blue, Color::Black).into())
        .thumb_style((Color::Yellow, Modifier::BOLD).into())
        .arrow_style((Color::LightGreen, Color::Black, Modifier::BOLD).into());
    let vertical = ScrollBar::vertical(lengths)
        .offset(80)
        .arrows(ScrollBarArrows::Both)
        .glyph_set(GlyphSet::box_drawing())
        .track_style((Color::Magenta, Color::Black).into())
        .thumb_style((Color::Cyan, Modifier::BOLD).into())
        .arrow_style((Color::LightRed, Color::Black, Modifier::BOLD).into());

    frame.render_widget(&horizontal, horizontal_bar);
    frame.render_widget(&vertical, vertical_bar);
}

examples/scrollbar_mouse.rs (line 200)

    fn render(&mut self, frame: &mut ratatui::Frame) {
        let area = frame.area();
        if area.width < 2 || area.height < 2 {
            return;
        }

        let title = "tui-scrollbar - mouse scroll demo";
        let block = Block::new()
            .borders(Borders::TOP)
            .border_style(Style::new().fg(TITLE_FG).bg(TITLE_BG))
            .style(Style::new().fg(BLOCK_FG).bg(BLOCK_BG))
            .title(
                Line::from(title)
                    .centered()
                    .fg(TITLE_FG)
                    .bg(TITLE_BG)
                    .bold(),
            );
        frame.render_widget(&block, area);

        let content_area = Rect {
            y: area.y.saturating_add(1),
            height: area.height.saturating_sub(1),
            ..area
        };
        let help = "Arrows: move | Wheel: scroll | Drag: thumb | q/Esc: quit";
        let help_area = Rect {
            x: content_area.x.saturating_add(1),
            y: content_area.y,
            width: content_area.width.saturating_sub(1),
            height: 1,
        };
        if help_area.width > 0 {
            frame.render_widget(
                Paragraph::new(help).style(Style::new().fg(TITLE_FG)),
                help_area,
            );
        }
        let content_area = Rect {
            y: content_area.y.saturating_add(1),
            height: content_area.height.saturating_sub(1),
            ..content_area
        };

        // Split out the bottom row and right column for the scrollbars.
        let [content_row, bar_row] = content_area.layout(&Layout::vertical([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [content, vertical_bar] = content_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [horizontal_bar, _corner] = bar_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));

        self.layout = Some(LayoutState {
            content,
            vertical_bar,
            horizontal_bar,
        });

        // Keep offsets valid when the terminal is resized.
        let (h_metrics, v_metrics) = self.metrics_for_layout(content);
        self.horizontal_offset = self.horizontal_offset.min(h_metrics.max_offset());
        self.vertical_offset = self.vertical_offset.min(v_metrics.max_offset());

        let horizontal_lengths = ScrollLengths {
            content_len: h_metrics.content_len(),
            viewport_len: h_metrics.viewport_len(),
        };
        let track_style = Style::new().bg(SCROLLBAR_TRACK_BG);
        let thumb_style = Style::new().fg(SCROLLBAR_THUMB_FG).bg(SCROLLBAR_THUMB_BG);
        let arrow_style = Style::new().fg(SCROLLBAR_ARROW_FG).bg(SCROLLBAR_TRACK_BG);
        let horizontal = ScrollBar::horizontal(horizontal_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);
        let vertical_lengths = ScrollLengths {
            content_len: v_metrics.content_len(),
            viewport_len: v_metrics.viewport_len(),
        };
        let vertical = ScrollBar::vertical(vertical_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.vertical_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);

        frame.render_widget(&horizontal, horizontal_bar);
        frame.render_widget(&vertical, vertical_bar);
    }

    /// Handles keyboard and mouse events, updating offsets as needed.
    fn handle_events(&mut self) -> Result<()> {
        match event::read()? {
            Event::Key(key) => {
                if key.is_press() {
                    self.handle_key_event(key.code);
                }
            }
            Event::Mouse(event) => {
                self.handle_mouse_event(event);
            }
            _ => {}
        }
        Ok(())
    }

    /// Handles keyboard input, updating offsets or exiting as needed.
    fn handle_key_event(&mut self, code: KeyCode) {
        match code {
            KeyCode::Char('q') | KeyCode::Esc => self.state = AppState::Quit,
            KeyCode::Up | KeyCode::Char('k') => self.handle_key_scroll(0, -(KEY_STEP as isize)),
            KeyCode::Down | KeyCode::Char('j') => self.handle_key_scroll(0, KEY_STEP as isize),
            KeyCode::Left | KeyCode::Char('h') => self.handle_key_scroll(-(KEY_STEP as isize), 0),
            KeyCode::Right | KeyCode::Char('l') => self.handle_key_scroll(KEY_STEP as isize, 0),
            _ => {}
        }
    }

    /// Applies a keyboard delta to the scrollbar offsets.
    fn handle_key_scroll(&mut self, dx: isize, dy: isize) {
        let Some(layout) = self.layout else {
            return;
        };
        let (h_metrics, v_metrics) = self.metrics_for_layout(layout.content);
        self.horizontal_offset =
            Self::apply_delta(self.horizontal_offset, dx, h_metrics.max_offset());
        self.vertical_offset = Self::apply_delta(self.vertical_offset, dy, v_metrics.max_offset());
    }

    /// Handles crossterm mouse events using the scrollbar helpers.
    fn handle_mouse_event(&mut self, event: event::MouseEvent) {
        let Some(layout) = self.layout else {
            return;
        };
        let (h_metrics, v_metrics) = self.metrics_for_layout(layout.content);
        let horizontal = self.horizontal_scrollbar(h_metrics);
        let vertical = self.vertical_scrollbar(v_metrics);

        if let Some(command) = horizontal.handle_mouse_event(
            layout.horizontal_bar,
            event,
            &mut self.horizontal_interaction,
        ) {
            self.apply_command(command, true);
        }
        if let Some(command) =
            vertical.handle_mouse_event(layout.vertical_bar, event, &mut self.vertical_interaction)
        {
            self.apply_command(command, false);
        }
    }

    /// Applies a scroll command to the current axis offset.
    fn apply_command(&mut self, command: ScrollCommand, is_horizontal: bool) {
        let ScrollCommand::SetOffset(offset) = command;
        if is_horizontal {
            self.horizontal_offset = offset;
        } else {
            self.vertical_offset = offset;
        }
    }

    /// Builds a horizontal scrollbar from the current metrics.
    fn horizontal_scrollbar(&self, metrics: ScrollMetrics) -> ScrollBar {
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        ScrollBar::horizontal(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
    }

    /// Builds a vertical scrollbar from the current metrics.
    fn vertical_scrollbar(&self, metrics: ScrollMetrics) -> ScrollBar {
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        ScrollBar::vertical(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.vertical_offset)
            .scroll_step(SUBCELL)
    }

pub const fn track_click_behavior(self, behavior: TrackClickBehavior) -> Self

Sets behavior for clicks on the track outside the thumb.

Use TrackClickBehavior::Page for classic page-up/down behavior, or TrackClickBehavior::JumpToClick to move the thumb toward the click.

This does not affect clicks on the thumb or arrow endcaps.

use tui_scrollbar::{ScrollBar, ScrollLengths, TrackClickBehavior};

let lengths = ScrollLengths {
    content_len: 120,
    viewport_len: 40,
};
let scrollbar =
    ScrollBar::vertical(lengths).track_click_behavior(TrackClickBehavior::JumpToClick);

pub fn scroll_step(self, step: usize) -> Self

Sets the scroll step used for wheel events.

The wheel delta is multiplied by this value (in your logical units) and then clamped. A step of 0 is normalized to 1.

use tui_scrollbar::{ScrollBar, ScrollLengths};

let lengths = ScrollLengths {
    content_len: 120,
    viewport_len: 40,
};
let scrollbar = ScrollBar::vertical(lengths).scroll_step(8);

Examples found in repository

examples/scrollbar_mouse.rs (line 202)

    fn render(&mut self, frame: &mut ratatui::Frame) {
        let area = frame.area();
        if area.width < 2 || area.height < 2 {
            return;
        }

        let title = "tui-scrollbar - mouse scroll demo";
        let block = Block::new()
            .borders(Borders::TOP)
            .border_style(Style::new().fg(TITLE_FG).bg(TITLE_BG))
            .style(Style::new().fg(BLOCK_FG).bg(BLOCK_BG))
            .title(
                Line::from(title)
                    .centered()
                    .fg(TITLE_FG)
                    .bg(TITLE_BG)
                    .bold(),
            );
        frame.render_widget(&block, area);

        let content_area = Rect {
            y: area.y.saturating_add(1),
            height: area.height.saturating_sub(1),
            ..area
        };
        let help = "Arrows: move | Wheel: scroll | Drag: thumb | q/Esc: quit";
        let help_area = Rect {
            x: content_area.x.saturating_add(1),
            y: content_area.y,
            width: content_area.width.saturating_sub(1),
            height: 1,
        };
        if help_area.width > 0 {
            frame.render_widget(
                Paragraph::new(help).style(Style::new().fg(TITLE_FG)),
                help_area,
            );
        }
        let content_area = Rect {
            y: content_area.y.saturating_add(1),
            height: content_area.height.saturating_sub(1),
            ..content_area
        };

        // Split out the bottom row and right column for the scrollbars.
        let [content_row, bar_row] = content_area.layout(&Layout::vertical([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [content, vertical_bar] = content_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [horizontal_bar, _corner] = bar_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));

        self.layout = Some(LayoutState {
            content,
            vertical_bar,
            horizontal_bar,
        });

        // Keep offsets valid when the terminal is resized.
        let (h_metrics, v_metrics) = self.metrics_for_layout(content);
        self.horizontal_offset = self.horizontal_offset.min(h_metrics.max_offset());
        self.vertical_offset = self.vertical_offset.min(v_metrics.max_offset());

        let horizontal_lengths = ScrollLengths {
            content_len: h_metrics.content_len(),
            viewport_len: h_metrics.viewport_len(),
        };
        let track_style = Style::new().bg(SCROLLBAR_TRACK_BG);
        let thumb_style = Style::new().fg(SCROLLBAR_THUMB_FG).bg(SCROLLBAR_THUMB_BG);
        let arrow_style = Style::new().fg(SCROLLBAR_ARROW_FG).bg(SCROLLBAR_TRACK_BG);
        let horizontal = ScrollBar::horizontal(horizontal_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);
        let vertical_lengths = ScrollLengths {
            content_len: v_metrics.content_len(),
            viewport_len: v_metrics.viewport_len(),
        };
        let vertical = ScrollBar::vertical(vertical_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.vertical_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);

        frame.render_widget(&horizontal, horizontal_bar);
        frame.render_widget(&vertical, vertical_bar);
    }

    /// Handles keyboard and mouse events, updating offsets as needed.
    fn handle_events(&mut self) -> Result<()> {
        match event::read()? {
            Event::Key(key) => {
                if key.is_press() {
                    self.handle_key_event(key.code);
                }
            }
            Event::Mouse(event) => {
                self.handle_mouse_event(event);
            }
            _ => {}
        }
        Ok(())
    }

    /// Handles keyboard input, updating offsets or exiting as needed.
    fn handle_key_event(&mut self, code: KeyCode) {
        match code {
            KeyCode::Char('q') | KeyCode::Esc => self.state = AppState::Quit,
            KeyCode::Up | KeyCode::Char('k') => self.handle_key_scroll(0, -(KEY_STEP as isize)),
            KeyCode::Down | KeyCode::Char('j') => self.handle_key_scroll(0, KEY_STEP as isize),
            KeyCode::Left | KeyCode::Char('h') => self.handle_key_scroll(-(KEY_STEP as isize), 0),
            KeyCode::Right | KeyCode::Char('l') => self.handle_key_scroll(KEY_STEP as isize, 0),
            _ => {}
        }
    }

    /// Applies a keyboard delta to the scrollbar offsets.
    fn handle_key_scroll(&mut self, dx: isize, dy: isize) {
        let Some(layout) = self.layout else {
            return;
        };
        let (h_metrics, v_metrics) = self.metrics_for_layout(layout.content);
        self.horizontal_offset =
            Self::apply_delta(self.horizontal_offset, dx, h_metrics.max_offset());
        self.vertical_offset = Self::apply_delta(self.vertical_offset, dy, v_metrics.max_offset());
    }

    /// Handles crossterm mouse events using the scrollbar helpers.
    fn handle_mouse_event(&mut self, event: event::MouseEvent) {
        let Some(layout) = self.layout else {
            return;
        };
        let (h_metrics, v_metrics) = self.metrics_for_layout(layout.content);
        let horizontal = self.horizontal_scrollbar(h_metrics);
        let vertical = self.vertical_scrollbar(v_metrics);

        if let Some(command) = horizontal.handle_mouse_event(
            layout.horizontal_bar,
            event,
            &mut self.horizontal_interaction,
        ) {
            self.apply_command(command, true);
        }
        if let Some(command) =
            vertical.handle_mouse_event(layout.vertical_bar, event, &mut self.vertical_interaction)
        {
            self.apply_command(command, false);
        }
    }

    /// Applies a scroll command to the current axis offset.
    fn apply_command(&mut self, command: ScrollCommand, is_horizontal: bool) {
        let ScrollCommand::SetOffset(offset) = command;
        if is_horizontal {
            self.horizontal_offset = offset;
        } else {
            self.vertical_offset = offset;
        }
    }

    /// Builds a horizontal scrollbar from the current metrics.
    fn horizontal_scrollbar(&self, metrics: ScrollMetrics) -> ScrollBar {
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        ScrollBar::horizontal(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
    }

    /// Builds a vertical scrollbar from the current metrics.
    fn vertical_scrollbar(&self, metrics: ScrollMetrics) -> ScrollBar {
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        ScrollBar::vertical(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.vertical_offset)
            .scroll_step(SUBCELL)
    }

Trait Implementations

impl Clone for ScrollBar

fn clone(&self) -> ScrollBar

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ScrollBar

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

Formats the value using the given formatter.

impl Eq for ScrollBar

impl PartialEq for ScrollBar

fn eq(&self, other: &ScrollBar) -> 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 StructuralPartialEq for ScrollBar

impl Widget for &ScrollBar

fn render(self, area: Rect, buf: &mut Buffer)

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.