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

impl ScrollBar

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

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

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

pub fn horizontal(lengths: ScrollLengths) -> ScrollBar

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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<(), Error>

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.