Class cli.MultiSelect

A multi-choice interactive checkbox widget for CLI tools.

This module provides a way to create a checkbox list, allowing the user to toggle multiple options using Space, navigate with arrow keys, and confirm with Enter. Type-ahead search navigates to a matching entry. The selected options are highlighted, and the user can confirm with Enter. Optionally the widget can be cancelled by pressing <esc> or <ctrl+c>.

NOTE: you MUST call terminal.initialize before calling this widget's :run() method.

Usage:

local menu = cli.MultiSelect{
  prompt = "Select options:",
  choices = {
    { label = "Option 1", key = "opt1", value = false },
    { label = "Option 2", key = "opt2", value = true },
    { label = "Option 3", value = false },  -- key defaults to label
  },
  cancellable = true
}

local result = menu()  -- invokes the 'run' method
-- result = { opt1 = false, opt2 = true, ["Option 3"] = false }

Functions

cli.MultiSelect (opts) Create a new MultiSelect instance.

Methods

cli.multiselect:clear_widget () Clears the widget.
cli.multiselect:height () Returns the display height in rows.
cli.multiselect:print_selection () Prints a one-line summary showing the count of checked items.
cli.multiselect:run () Executes the widget.
cli.multiselect:set_selection (idx) Set the current cursor position.


Functions

cli.MultiSelect (opts)
Create a new MultiSelect instance.

Parameters:

  • opts Options for the MultiSelect widget.
    • choices table List of choices. Each entry is a table with: label (string, required), key (any type, optional, defaults to label), value (boolean, optional, initial checked state, defaults to false).
    • default number Default cursor position (1-based index into choices). (default 1)
    • prompt string Prompt message to display. (default "Select options:")
    • cancellable boolean Whether the widget can be cancelled (by pressing <esc> or <ctrl+c>). (default false)
    • clear boolean Whether to clear the widget from screen after completion. (default false)
    • typeahead_delay number Seconds of inactivity after which the typeahead search buffer resets. (default 1.0)
    • checked_sym string Symbol displayed in front of a checked item. (default "● ")
    • unchecked_sym string Symbol displayed in front of an unchecked item. (default "○ ")

Returns:

    MultiSelect A new MultiSelect instance.

Methods

cli.multiselect:clear_widget ()
Clears the widget.
cli.multiselect:height ()
Returns the display height in rows.

Returns:

    number The height of the widget in rows.
cli.multiselect:print_selection ()
Prints a one-line summary showing the count of checked items.
cli.multiselect:run ()
Executes the widget. If necessary it initializes the terminal first. It also handles the cleanup of the terminal state after the widget is closed.

Returns:

  1. table or nil Hash table { [key] = bool } for each choice, or nil if cancelled.
  2. string or nil nil on success, "cancelled" if cancelled.
cli.multiselect:set_selection (idx)
Set the current cursor position.

Parameters:

  • idx number The index to set as the current cursor position (1-based).
generated by LDoc 1.5.0