class RatatuiRuby::Widgets::List

Displays a selectable list of items.

Users need to choose from options. Menus, file explorers, and selectors are everywhere. Implementing navigation, highlighting, and scrolling state from scratch is tedious.

This widget manages the list. It renders the items. It highlights the selection. It handles the scrolling window.

Use it to build main menus, navigation sidebars, or logs.

Examples

# Basic List
List.new(items: ["Item 1", "Item 2"])

# Navigation Menu
List.new(
  items: ["New Game", "Load Game", "Options", "Quit"],
  selected_index: 0,
  highlight_style: Style.new(bg: :blue),
  highlight_symbol: ">> "
)

Constants

DIRECTION_BOTTOM_TO_TOP: Direction: render items from bottom to top.
DIRECTION_TOP_TO_BOTTOM: Direction: render items from top to bottom (default).
HIGHLIGHT_ALWAYS: Highlight spacing: always show the spacing column.
HIGHLIGHT_NEVER: Highlight spacing: never show the spacing column.
HIGHLIGHT_WHEN_SELECTED: Highlight spacing: show spacing only when an item is selected (default).

Attributes

block [R]

Optional wrapping block.

direction [R]

Render direction.

:top_to_bottom or :bottom_to_top.

highlight_spacing [R]

When to show the highlight symbol column.

:always, :when_selected, or :never.

highlight_style [R]

Style for the selected item.

highlight_symbol [R]

Symbol drawn before the selected item.

items [R]

The items to display.

Accepts Array of Strings, Text::Spans, Text::Lines, or ListItem objects. For styled individual rows, use ListItem with a style.

offset [R]

Scroll offset (Integer or nil).

Controls the viewport’s starting position in the list.

When nil (default), Ratatui auto-scrolls to keep the selection visible (“natural scrolling”).

When set, forces the viewport to start at this item index. Use this for:

**Passive scrolling**: Scroll through a log viewer without selecting items.
**Click-to-select math**: Calculate which item index corresponds to a click coordinate.

Important: When both offset and selected_index are set, Ratatui may still adjust the viewport during rendering to ensure the selection stays visible. Set selected_index to nil for fully manual scroll control.

repeat_highlight_symbol [R]

Whether to repeat the highlight symbol for each line of the selected item.

scroll_padding [R]

Number of items to keep visible above/below the selected item when scrolling (Integer or nil).

selected_index [R]

Index of the active selection (Integer or nil).

style [R]

Base style for unselected items.

Public Class Methods

new (items: [], selected_index: nil, offset: nil, style: nil, highlight_style: nil, highlight_symbol: "> ", repeat_highlight_symbol: false, highlight_spacing: :when_selected, direction: :top_to_bottom, scroll_padding: nil, block: nil)

Source

# File lib/ratatui_ruby/widgets/list.rb, line 139
def initialize(items: [], selected_index: nil, offset: nil, style: nil, highlight_style: nil, highlight_symbol: "> ", repeat_highlight_symbol: false, highlight_spacing: :when_selected, direction: :top_to_bottom, scroll_padding: nil, block: nil)
  super(
    items:,
    selected_index: selected_index.nil? ? nil : Integer(selected_index),
    offset: offset.nil? ? nil : Integer(offset),
    style:,
    highlight_style:,
    highlight_symbol:,
    repeat_highlight_symbol:,
    highlight_spacing:,
    direction:,
    scroll_padding: scroll_padding.nil? ? nil : Integer(scroll_padding),
    block:
  )
end

Creates a new List.

Integer parameters accept any object responding to to_int or to_i (duck-typed).

items: Array of Strings, Text::Spans, Text::Lines, or ListItem objects.
selected_index: Numeric (nullable, coerced to Integer).
offset: Numeric (nullable, coerced to Integer). Forces scroll position when set.
style: Style object.
highlight_style: Style object.
highlight_symbol: String (default: "> ").
repeat_highlight_symbol: Boolean (default: false).
highlight_spacing: Symbol (default: :when_selected).
direction: Symbol (default: :top_to_bottom).
scroll_padding: Numeric (nullable, coerced to Integer, default: nil).
block: Block (optional).

Calls superclass method

Public Instance Methods

empty? ()

Source

# File lib/ratatui_ruby/widgets/list.rb, line 194
def empty?
  items.empty?
end

Returns true if the list contains no items.

Example

list = Widgets::List.new(items: [])
list.empty?  # => true

Returns: Boolean.

len ()

Source

# File lib/ratatui_ruby/widgets/list.rb, line 214
def len
  items.length
end

Returns the number of items in the list.

Example

list = Widgets::List.new(items: %w[alpha beta gamma])
list.len  # => 3

Returns: Integer.

Also aliased as: length, size

length ()

Alias for: len

selected? ()

Source

# File lib/ratatui_ruby/widgets/list.rb, line 174
def selected?
  !selected_index.nil?
end

Returns true if an item is selected.

Example

list = Widgets::List.new(items: %w[a b c])
list.selected?  # => false

list = Widgets::List.new(items: %w[a b c], selected_index: 1)
list.selected?  # => true

Returns: Boolean.

selected_item ()

Source

# File lib/ratatui_ruby/widgets/list.rb, line 245
def selected_item
  return nil if selected_index.nil?

  items[selected_index]
end

Returns the currently selected item, or nil if nothing is selected.

Accessing the selected item directly requires looking up items[selected_index] after checking that selected_index is not nil. This is verbose.

This method encapsulates that pattern.

Example

list = Widgets::List.new(items: %w[alpha beta gamma], selected_index: 1)
list.selected_item  # => "beta"

Returns: The item at the selected index, or nil if no selection.

size ()

Alias for: len