SelectableListPrompt<T> class

SelectableListPrompt – composable system for list-based selection prompts.

Eliminates boilerplate by composing:

Design principles:

  • Composition over inheritance
  • Separation of concerns (each component remains independent)
  • Builder pattern for flexible configuration
  • DRY: Centralizes common prompt/view patterns
  • Backward compatible: Individual components still work standalone

Before SelectableListPrompt:

final nav = ListNavigator(itemCount: items.length, maxVisible: 10);
final selection = SelectionController.multi();
bool cancelled = false;

final bindings = KeyBindings.verticalNavigation(
  onUp: () => nav.moveUp(),
  onDown: () => nav.moveDown(),
) + KeyBindings.toggle(
  onToggle: () => selection.toggle(nav.selectedIndex),
) + KeyBindings.prompt(onCancel: () => cancelled = true);

final frame = FrameView(title: title, theme: theme, bindings: bindings);

void render(RenderOutput out) {
  frame.render(out, (ctx) {
    final window = nav.visibleWindow(items);
    ctx.listWindow(window, selectedIndex: nav.selectedIndex, ...);
  });
}

final runner = PromptRunner(hideCursor: true);
final result = runner.runWithBindings(render: render, bindings: bindings);

if (cancelled || result == PromptResult.cancelled) return [];
return selection.getSelectedMany(items, fallbackIndex: nav.selectedIndex);

After SelectableListPrompt:

final prompt = SelectableListPrompt(
  title: title,
  items: items,
  theme: theme,
  multiSelect: true,
);

final result = prompt.run(
  renderItem: (ctx, item, index, focused, selected) {
    ctx.checkboxItem(item, focused: focused, checked: selected);
  },
);

Advanced usage with custom content:

final prompt = SelectableListPrompt(
  title: title,
  items: items,
  theme: theme,
);

final result = prompt.runCustom(
  beforeItems: (ctx) => ctx.searchLine(query),
  renderItem: (ctx, item, index, focused, selected) { ... },
  afterItems: (ctx) => ctx.summaryLine(selection.count, items.length),
);
Available extensions

Constructors

SelectableListPrompt({required String title, required List<T> items, PromptTheme theme = PromptTheme.dark, bool multiSelect = false, int maxVisible = 12, Set<int>? initialSelection, int reservedLines = 7})

Properties

bindings → KeyBindings
Current key bindings. Available during run callbacks.
no setter
hashCode → int
The hash code for this object.
no setterinherited
initialSelection → Set<int>?
Initial selection indices.
final
items → List<T>
Items to select from.
final
maxVisible → int
Maximum visible items (viewport size).
final
multiSelect → bool
Whether multiple items can be selected.
final
Current navigation state. Available during run callbacks.
no setter
reservedLines → int
Terminal lines to reserve for chrome (headers, hints, etc).
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
selection → SelectionController
Current selection state. Available during run callbacks.
no setter
theme → PromptTheme
Theme for styling.
final
title → String
Title for the frame header.
final
wasCancelled → bool
Whether the prompt was cancelled. Available after run completes.
no setter

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
run({required void renderItem(FrameContext ctx, T item, int absoluteIndex, bool isFocused, bool isSelected), KeyBindings? extraBindings}) → List<T>
Runs the prompt with simple item rendering.
runCustom({void beforeItems(FrameContext ctx)?, required void renderItem(FrameContext ctx, T item, int absoluteIndex, bool isFocused, bool isSelected), void afterItems(FrameContext ctx)?, KeyBindings? extraBindings, void onBeforeRender()?}) → List<T>
Runs the prompt with full customization hooks.
selectAllBindings({String hintDescription = 'select all / clear'}) → KeyBindings

Available on SelectableListPrompt<T>, provided by the SelectableListPromptExt extension

Creates bindings for select all ('A' key).
summaryLine() → String

Available on SelectableListPrompt<T>, provided by the SelectableListPromptExt extension

Creates a summary line showing selection count.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

multi<T>({required String title, required List<T> items, PromptTheme theme = PromptTheme.dark, int maxVisible = 12, Set<int>? initialSelection, String labelBuilder(T)?, bool withSelectAll = true}) → List<T>
Creates a multi-select prompt with checkbox UI.
single<T>({required String title, required List<T> items, PromptTheme theme = PromptTheme.dark, int maxVisible = 12, String labelBuilder(T)?}) → T?
Creates a single-select prompt.