Class: RatatuiRuby::Widgets::List

Inherits:
Object
  • Object
show all
Includes:
CoerceableWidget
Defined in:
lib/ratatui_ruby/widgets/list.rb

Overview

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

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

# 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: ">> "
)

– SPDX-SnippetEnd ++

Constant Summary collapse

HIGHLIGHT_ALWAYS =

Highlight spacing: always show the spacing column.

:always
HIGHLIGHT_WHEN_SELECTED =

Highlight spacing: show spacing only when an item is selected (default).

:when_selected
HIGHLIGHT_NEVER =

Highlight spacing: never show the spacing column.

:never
DIRECTION_TOP_TO_BOTTOM =

Direction: render items from top to bottom (default).

:top_to_bottom
DIRECTION_BOTTOM_TO_TOP =

Direction: render items from bottom to top.

:bottom_to_top

Instance Method Summary collapse

Methods included from CoerceableWidget

included

Constructor Details

#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) ⇒ List

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



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# 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

Instance Method Details

#empty? ⇒ Boolean

Returns true if the list contains no items.

Example

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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

– SPDX-SnippetEnd ++ Returns: Boolean.

Returns:

  • (Boolean) 


194
195
196
 
# File 'lib/ratatui_ruby/widgets/list.rb', line 194

def empty?
  items.empty?
end

#len ⇒ Object Also known as: length, size

Returns the number of items in the list.

Example

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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

– SPDX-SnippetEnd ++ Returns: Integer.



214
215
216
 
# File 'lib/ratatui_ruby/widgets/list.rb', line 214

def len
  items.length
end

#selected? ⇒ Boolean

Returns true if an item is selected.

Example

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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

– SPDX-SnippetEnd ++ Returns: Boolean.

Returns:

  • (Boolean) 


174
175
176
 
# File 'lib/ratatui_ruby/widgets/list.rb', line 174

def selected?
  !selected_index.nil?
end

#selected_item ⇒ Object

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

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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

– SPDX-SnippetEnd ++ Returns: The item at the selected index, or nil if no selection.



245
246
247
248
249
 
# File 'lib/ratatui_ruby/widgets/list.rb', line 245

def selected_item
  return nil if selected_index.nil?

  items[selected_index]
end