wijjit.elements.input.checkbox.CheckboxGroup

class wijjit.elements.input.checkbox.CheckboxGroup(id=None, classes=None, tab_index=None, options=None, selected_values=None, width=20, orientation='vertical', border_style=None, title=None, bind=True)

Group of checkboxes for multiple selections.

A convenience container that manages multiple checkboxes as a single unit, with optional borders and titles. Selected values are stored as a list.

Parameters:

• id (str, optional) – Element identifier

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

• selected_values (list, optional) – List of initially selected values

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

• orientation ({"vertical", "horizontal"}, optional) – Layout orientation (default: “vertical”)

• border_style (BorderStyle or {"single", "double", "rounded"} or None, optional) – Border style for the group (default: None). - “single”: Single-line box-drawing characters - “double”: Double-line box-drawing characters - “rounded”: Rounded corner box-drawing characters - None: No borders 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)

• bind (bool | str)

Variables:

• options (list) – Available options

• selected_values (list) – Currently selected values

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

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

• orientation (str) – Layout orientation

• 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: [“Option A”, “Option B”, “Option C”] - Value/label dicts: [{“value”: “a”, “label”: “Option A”}, …]

Navigation: - Up/Down (vertical) or Left/Right (horizontal): Navigate options - Space/Enter: Toggle highlighted option (Enter also triggers action)

__init__(id=None, classes=None, tab_index=None, options=None, selected_values=None, width=20, orientation='vertical', border_style=None, title=None, bind=True)

Parameters:

• id (str | None)

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

• tab_index (int | None)

• options (list[Any] | None)

• selected_values (list[Any] | None)

• width (int)

• orientation (Literal['vertical', 'horizontal'])

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

• title (str | None)

• bind (bool | str)

Methods

__init__([id, classes, tab_index, options, ...])
add_class(class_name)	Add a CSS class to this element.
apply_props(props)	Apply props from a VNode, skipping ephemeral props.
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 size of the checkbox group.
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()	Paint memo for the skip-unchanged fast path.
render_to(ctx)	Render checkbox group using cell-based rendering.
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.
toggle_option(index)	Toggle selection of option at index.

Attributes

captures_tab	Whether this element wants the Tab key instead of focus movement.
highlight_state_key	Get the state key for highlighted index.
parent_frame	Get the parent Frame if this element is inside a scrollable frame.
supports_dynamic_sizing	Whether this element supports dynamic sizing.

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

toggle_option(index)

Toggle selection of option at index.

Parameters:

index (int) – Index of option to toggle

Return type:

None

handle_key(key)

Handle keyboard input.

Parameters:

key (Key)

Return type:

bool

async handle_mouse(event)

Handle mouse input.

Parameters:

event (MouseEvent)

Return type:

bool

render_signature()

Paint memo for the skip-unchanged fast path.

Captures the options, the selected set (snapshotted - it is mutated in place by toggle_option()), the keyboard highlight, and the border/layout inputs the paint reads. See wijjit.elements.base.Element.render_signature().

Return type:

Any

render_to(ctx)

Render checkbox group using cell-based rendering.

Parameters:

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

• styles (Theme)

• classes (This element uses the following theme style)

• checkbox (-)

• checkbox:checked (-)

• frame.border (-)

• text.title (-)

Return type:

None

get_ephemeral_state()

Get ephemeral state for reconciliation.

Returns:

Highlight 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

get_intrinsic_size()

Get the intrinsic size of the checkbox group.

Returns:

(width, height) based on options and orientation

Return type:

tuple[int, int]

Notes

For vertical orientation: height = number of options (+ 2 for borders) For horizontal orientation: height = 1 (+ 2 for borders) Width includes border characters if borders are enabled.