class RatatuiRuby::ListState

Mutable state object for List widgets.

When using {Frame#render_stateful_widget}, the State object is the *single source of truth* for selection and scroll offset. Widget properties (selected_index, offset) are ignored in stateful mode.

State objects persist across frames, allowing you to:

Track selection without manual index management
Read back the scroll offset calculated by Ratatui
Implement mouse click-to-row hit testing

Thread/Ractor Safety

ListState is not Ractor-shareable. It contains mutable internal state. Store it in instance variables, not in immutable Models.

Example

@list_state = RatatuiRuby::ListState.new
@list_state.select(2) # Select third item

RatatuiRuby.draw do |frame|
  list = RatatuiRuby::Widgets::List.new(items: ["A", "B", "C", "D", "E"])
  frame.render_stateful_widget(list, frame.area, @list_state)
end

puts @list_state.offset # Scroll position after render

Public Instance Methods

new(selected = nil) → ListState

Source

# File lib/ratatui_ruby/list_state.rb, line 47

Creates a new ListState with optional initial selection.

(Native method implemented in Rust)

offset() → Integer

Source

# File lib/ratatui_ruby/list_state.rb, line 71

Returns the current scroll offset.

This is the critical read-back method. After render_stateful_widget, this returns the scroll position calculated by Ratatui to keep the selection visible.

(Native method implemented in Rust)

scroll_down_by(n) → nil

Source

# File lib/ratatui_ruby/list_state.rb, line 83

Scrolls down by n items.

(Native method implemented in Rust)

scroll_up_by(n) → nil

Source

# File lib/ratatui_ruby/list_state.rb, line 91

Scrolls up by n items.

(Native method implemented in Rust)

select(index) → nil

Source

# File lib/ratatui_ruby/list_state.rb, line 55

Sets the selected index. Pass nil to deselect.

(Native method implemented in Rust)

select_first() → nil

Source

# File lib/ratatui_ruby/list_state.rb, line 156

Jumps selection to the first item (index 0).

To detect actual selection changes:

return if (state.selected || 0) == 0
state.select_first

(Native method implemented in Rust)

select_last() → nil

Source

# File lib/ratatui_ruby/list_state.rb, line 177

Jumps selection to the last item.

Optimistic Indexing

Sets index to maximum possible value. The renderer clamps to actual last item on draw. To get or check the real last index, track item count:

max_index = items.size - 1
return if (state.selected || 0) == max_index
state.select(max_index)

(Native method implemented in Rust)

select_next() → nil

Source

# File lib/ratatui_ruby/list_state.rb, line 99

Moves selection to the next item. Selects first item if nothing selected.

Optimistic Indexing

Increments the index immediately, even past list bounds. The renderer clamps to valid range on draw. Reading selected between this call and render may return an out-of-bounds value.

Matches upstream Ratatui behavior. See ListState#select_next.

To detect actual selection changes, check bounds first:

max_index = items.size - 1
return if (state.selected || 0) >= max_index
state.select_next

(Native method implemented in Rust)

select_previous() → nil

Source

# File lib/ratatui_ruby/list_state.rb, line 130

Moves selection to the previous item. Selects last item if nothing selected.

Optimistic Indexing

At index 0, does nothing. With no selection, sets index to maximum value; the renderer clamps to actual last item on draw.

To detect actual selection changes, check bounds first:

return if (state.selected || 0) <= 0
state.select_previous

(Native method implemented in Rust)

selected() → Integer or nil

Source

# File lib/ratatui_ruby/list_state.rb, line 63

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

(Native method implemented in Rust)