Struct ScrollBar 

pub struct ScrollBar { /* private fields */ }

A proportional scrollbar widget with fractional thumb rendering.

Key methods

• Self::new
• Self::orientation
• Self::arrows
• Self::content_len
• Self::viewport_len
• Self::offset

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.

State

This widget is stateless. Pointer drag state lives in [ScrollBarInteraction].

Examples

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 offset.

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.

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.

pub fn horizontal(lengths: ScrollLengths) -> ScrollBar

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

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

Sets the scrollbar orientation.

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.

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.

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.

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

Sets the style applied to track glyphs.

Track styling applies only where the thumb is not rendered.

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

Sets the style applied to thumb glyphs.

Thumb styling overrides track styling for covered cells.

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

Sets the style applied to arrow glyphs.

Defaults to white on dark gray.

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 additional symbols for 1/8th upper/right fills. Use GlyphSet::unicode if you want to avoid the legacy supplement.

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

Sets which arrow endcaps are rendered.

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.

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.

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 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 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.

impl Eq for ScrollBar

impl StructuralPartialEq for ScrollBar