wijjit.elements.input.select.Select

class wijjit.elements.input.select.Select(id=None, classes=None, tab_index=None, options=None, value=None, values=None, multiple=False, width=20, visible_rows=5, disabled_values=None, placeholder='No options', on_change=None, border_style=None, title=None, bind=True)

Select list element for choosing from a scrollable list of options.

This is a fixed-height scrollable list selector suitable for TUI applications. Unlike web dropdowns, this is always visible and uses vertical space efficiently.

Parameters:

• id (str, optional) – Element identifier

• options (list, optional) – List of options (strings or dicts with ‘value’ and ‘label’ keys)

• value (str, optional) – Currently selected value (single-select mode)

• values (list, optional) – List of selected values (multi-select mode)

• multiple (bool, optional) – Enable multiple selection mode (default: False)

• width (int, optional) – Display width for content area (default: 20). Note: Borders add 2 additional columns to total width when enabled.

• visible_rows (int, optional) – Number of visible rows in the list (default: 5)

• disabled_values (list, optional) – List of values that are disabled (cannot be selected)

• placeholder (str, optional) – Text to display when options list is empty (default: “No options”)

• border_style (BorderStyle or {"single", "double", "rounded"} or None, optional) – Border style for the select list (default: None). - “single”: Single-line box-drawing characters - “double”: Double-line box-drawing characters - “rounded”: Rounded corner box-drawing characters - None: No borders (backward compatible) Can also accept BorderStyle enum values.

• title (str, optional) – Title to display in the top border (only shown when border_style is not None)

• classes (str | list[str] | set[str] | None)

• tab_index (int | None)

• on_change (Callable[[Any, Any], None] | None)

• bind (bool | str)

Variables:

• options (list) – Available options

• multiple (bool) – Whether multiple selection is enabled

• value (str or None) – Currently selected value (single-select mode)

• selected_values (set) – Set of selected values (multi-select mode)

• selected_index (int) – Index of selected option (-1 if none, single-select mode)

• highlighted_index (int) – Index of highlighted option for keyboard navigation

• width (int) – Display width (content area, excluding borders)

• visible_rows (int) – Number of visible rows

• disabled_values (set) – Set of disabled values

• placeholder (str) – Text to display when options list is empty

• scroll_manager (ScrollManager) – Manages scrolling of options list

• border_style (BorderStyle or None) – Border style for rendering

• title (str or None) – Title displayed in top border (when borders are enabled)

Notes

Options can be specified as: - Simple strings: [“Red”, “Green”, “Blue”] - Value/label dicts: [{“value”: “r”, “label”: “Red”}, …] - Mixed: [“Simple”, {“value”: “v”, “label”: “Complex”}]

Navigation: - Up/Down: Navigate options - Enter/Space: Select highlighted option (single) or toggle selection (multiple) - Home/End: Jump to first/last option - PageUp/PageDown: Scroll by page

__init__(id=None, classes=None, tab_index=None, options=None, value=None, values=None, multiple=False, width=20, visible_rows=5, disabled_values=None, placeholder='No options', on_change=None, border_style=None, title=None, bind=True)

Initialize scrollable element.

Parameters:

• id (str, optional) – Element identifier

• classes (str or list of str or set of str, optional) – CSS class names for styling

• tab_index (int, optional) – Tab order for focus navigation

• options (list[Any] | None)

• value (str | None)

• values (list[Any] | None)

• multiple (bool)

• width (int)

• visible_rows (int)

• disabled_values (list[Any] | None)

• placeholder (str)

• on_change (Callable[[Any, Any], None] | None)

• border_style (BorderStyle | Literal['single', 'double', 'rounded'] | None)

• title (str | None)

• bind (bool | str)

Methods

__init__([id, classes, tab_index, options, ...])	Initialize scrollable element.
add_class(class_name)	Add a CSS class to this element.
apply_props(props)	Apply props from a VNode, skipping ephemeral props.
can_scroll(direction)	Check if the element can scroll in the given direction.
get_ephemeral_state()	Get ephemeral state for reconciliation.
get_hardware_cursor_position()	Absolute screen cell where the hardware terminal cursor should park.
get_height_for_width(width)	Return the height this element needs when laid out at width.
get_intrinsic_size()	Get the intrinsic (preferred) size of the element.
handle_key(key)	Handle keyboard input.
handle_mouse(event)	Handle mouse input.
has_class(class_name)	Check if element has a CSS class.
on_blur()	Called when element loses focus.
on_focus()	Called when element gains focus.
on_hover_enter()	Called when mouse enters element.
on_hover_exit()	Called when mouse exits element.
on_mount()	Called when element is first added to the element tree.
on_unmount()	Called when element is removed from the element tree.
on_update(changed_props)	Called when element props are updated during reconciliation.
remove_class(class_name)	Remove a CSS class from this element.
render_signature()	Hashable/comparable capture of everything render_to() reads.
render_to(ctx)	Render the select element using cell-based rendering (NEW API).
restore_ephemeral_state(state)	Restore ephemeral state after reconciliation.
set_bounds(bounds)	Set the element's screen bounds.
toggle_class(class_name)	Toggle a CSS class on this element.

Attributes

captures_tab	Whether this element wants the Tab key instead of focus movement.
highlight_state_key	Get the state key for highlighted index.
options	Get the normalized options list.
parent_frame	Get the parent Frame if this element is inside a scrollable frame.
scroll_position	Get the current scroll position.
scroll_state_key	Get the state key for vertical scroll position.
scroll_state_key_x	Get the state key for horizontal scroll position.
supports_dynamic_sizing	Whether this element supports dynamic sizing.
values	Get the selected values as a list.

property highlight_state_key: str | None

Get the state key for highlighted index.

Returns the explicitly set key if provided, otherwise auto-generates from the element id using the convention “{id}:highlight”.

Returns:

State key for highlight, or None if no id

Return type:

str or None

property options: list[dict[str, Any]]

Get the normalized options list.

Returns:

Normalized options with ‘value’ and ‘label’ keys

Return type:

list of dict

on_focus()

Called when element gains focus.

Note: highlighted_index is preserved across renders via state persistence, so we don’t reset it here. It’s initialized correctly during __init__ (either from state restoration or defaults to selected_index).

Return type:

None

property values: list[str]

Get the selected values as a list.

In single-select mode, returns a list with one element (or empty). In multi-select mode, returns all selected values.

Returns:

List of selected values

Return type:

list of str

property scroll_position: int

Get the current scroll position.

Returns:

Current scroll offset (0-based)

Return type:

int

can_scroll(direction)

Check if the element can scroll in the given direction.

Parameters:

direction (int) – Scroll direction: negative for up, positive for down

Returns:

True if scrolling in the given direction is possible

Return type:

bool

handle_key(key)

Handle keyboard input.

Parameters:

key (Key) – Key press to handle

Returns:

True if key was handled

Return type:

bool

async handle_mouse(event)

Handle mouse input.

Parameters:

event (MouseEvent) – Mouse event to handle

Returns:

True if event was handled

Return type:

bool

render_to(ctx)

Render the select element using cell-based rendering (NEW API).

Parameters:

ctx (PaintContext) – Paint context with buffer, style resolver, and bounds

Return type:

None

Notes

This is the new cell-based rendering method that uses theme styles instead of hardcoded ANSI colors. It renders a scrollable list of options with optional borders and title.

Theme styles:

This element uses the following theme style classes: - select: Base select style - select:focus: Focused select style - select.border: Border style - select.border:focus: Focused border style - select.option: Option item style - select.option:selected: Selected option style (marked with an asterisk) - select.option:highlighted: Highlighted option style (keyboard focus) - select.option:disabled: Disabled option style - select.placeholder: Placeholder text style (empty state)

get_ephemeral_state()

Get ephemeral state for reconciliation.

Returns:

Highlight, scroll, and selection state that should survive re-renders

Return type:

dict

restore_ephemeral_state(state)

Restore ephemeral state after reconciliation.

Parameters:

state (dict) – State from get_ephemeral_state()

Return type:

None