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