Struct Scrollbar

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

A widget to display a scrollbar

The following components of the scrollbar are customizable in symbol and style. Note the scrollbar is represented horizontally but it can also be set vertically (which is actually the default).

<--▮------->
^  ^   ^   ^
│  │   │   └ end
│  │   └──── track
│  └──────── thumb
└─────────── begin

Important

You must specify the ScrollbarState::content_length before rendering the Scrollbar, or else the Scrollbar will render blank.

Examples

use ratatui::{
    layout::{Margin, Rect},
    text::Line,
    widgets::{
        Block, Borders, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState,
        StatefulWidget,
    },
    Frame,
};

let vertical_scroll = 0; // from app state

let items = vec![
    Line::from("Item 1"),
    Line::from("Item 2"),
    Line::from("Item 3"),
];
let paragraph = Paragraph::new(items.clone())
    .scroll((vertical_scroll as u16, 0))
    .block(Block::new().borders(Borders::RIGHT)); // to show a background for the scrollbar

let scrollbar = Scrollbar::new(ScrollbarOrientation::VerticalRight)
    .begin_symbol(Some("↑"))
    .end_symbol(Some("↓"));

let mut scrollbar_state = ScrollbarState::new(items.len()).position(vertical_scroll);

let area = frame.area();
// Note we render the paragraph
frame.render_widget(paragraph, area);
// and the scrollbar, those are separate widgets
frame.render_stateful_widget(
    scrollbar,
    area.inner(Margin {
        // using an inner vertical margin of 1 unit makes the scrollbar inside the block
        vertical: 1,
        horizontal: 0,
    }),
    &mut scrollbar_state,
);

Implementations

impl<'a> Scrollbar<'a>

pub const fn new(orientation: ScrollbarOrientation) -> Self

Creates a new scrollbar with the given orientation.

Most of the time you’ll want ScrollbarOrientation::VerticalRight or ScrollbarOrientation::HorizontalBottom. See ScrollbarOrientation for more options.

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

Sets the position of the scrollbar.

The orientation of the scrollbar is the position it will take around a Rect. See ScrollbarOrientation for more details.

Resets the symbols to DOUBLE_VERTICAL or DOUBLE_HORIZONTAL based on orientation.

This is a fluent setter method which must be chained or used as it consumes self

pub const fn orientation_and_symbol( self, orientation: ScrollbarOrientation, symbols: Set, ) -> Self

Sets the orientation and symbols for the scrollbar from a Set.

This has the same effect as calling Scrollbar::orientation and then Scrollbar::symbols. See those for more details.

This is a fluent setter method which must be chained or used as it consumes self

pub const fn thumb_symbol(self, thumb_symbol: &'a str) -> Self

Sets the symbol that represents the thumb of the scrollbar.

The thumb is the handle representing the progression on the scrollbar. See Scrollbar for a visual example of what this represents.

This is a fluent setter method which must be chained or used as it consumes self

pub fn thumb_style<S: Into<Style>>(self, thumb_style: S) -> Self

Sets the style on the scrollbar thumb.

The thumb is the handle representing the progression on the scrollbar. See Scrollbar for a visual example of what this represents.

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

This is a fluent setter method which must be chained or used as it consumes self

pub const fn track_symbol(self, track_symbol: Option<&'a str>) -> Self

Sets the symbol that represents the track of the scrollbar.

See Scrollbar for a visual example of what this represents.

This is a fluent setter method which must be chained or used as it consumes self

pub fn track_style<S: Into<Style>>(self, track_style: S) -> Self

Sets the style that is used for the track of the scrollbar.

See Scrollbar for a visual example of what this represents.

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

This is a fluent setter method which must be chained or used as it consumes self

pub const fn begin_symbol(self, begin_symbol: Option<&'a str>) -> Self

Sets the symbol that represents the beginning of the scrollbar.

See Scrollbar for a visual example of what this represents.

This is a fluent setter method which must be chained or used as it consumes self

pub fn begin_style<S: Into<Style>>(self, begin_style: S) -> Self

Sets the style that is used for the beginning of the scrollbar.

See Scrollbar for a visual example of what this represents.

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

This is a fluent setter method which must be chained or used as it consumes self

pub const fn end_symbol(self, end_symbol: Option<&'a str>) -> Self

Sets the symbol that represents the end of the scrollbar.

See Scrollbar for a visual example of what this represents.

This is a fluent setter method which must be chained or used as it consumes self

pub fn end_style<S: Into<Style>>(self, end_style: S) -> Self

Sets the style that is used for the end of the scrollbar.

See Scrollbar for a visual example of what this represents.

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

This is a fluent setter method which must be chained or used as it consumes self

pub const fn symbols(self, symbols: Set) -> Self

Sets the symbols used for the various parts of the scrollbar from a Set.

<--▮------->
^  ^   ^   ^
│  │   │   └ end
│  │   └──── track
│  └──────── thumb
└─────────── begin

Only sets begin_symbol, end_symbol and track_symbol if they already contain a value. If they were set to None explicitly, this function will respect that choice. Use their respective setters to change their value.

This is a fluent setter method which must be chained or used as it consumes self

pub fn style<S: Into<Style>>(self, style: S) -> Self

Sets the style used for the various parts of the scrollbar from a Style.

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

<--▮------->
^  ^   ^   ^
│  │   │   └ end
│  │   └──── track
│  └──────── thumb
└─────────── begin

This is a fluent setter method which must be chained or used as it consumes self

Trait Implementations

impl<'a> Clone for Scrollbar<'a>

fn clone(&self) -> Scrollbar<'a>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Scrollbar<'a>

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

Formats the value using the given formatter.

impl<'a> Default for Scrollbar<'a>

fn default() -> Self

Returns the “default value” for a type.

impl<'a> Hash for Scrollbar<'a>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> PartialEq for Scrollbar<'a>

fn eq(&self, other: &Scrollbar<'a>) -> 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<'a> StatefulWidget for Scrollbar<'a>

type State = ScrollbarState

State associated with the stateful widget.

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

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

impl<'a> Eq for Scrollbar<'a>

impl<'a> StructuralPartialEq for Scrollbar<'a>