wijjit.elements.input.toggle.Toggle

class wijjit.elements.input.toggle.Toggle(id=None, classes=None, tab_index=None, checked=False, label=None, on_label='ON', off_label='OFF', label_mode='single', bind=True)[source]

Toggle switch element for boolean values.

A toggle switch provides a clear visual indicator for on/off states, distinct from a checkbox. Uses colored block characters to show state. Supports two label modes: - Single mode: Label displayed after the switch - Dual mode: Labels on both sides showing Off/On states

Parameters:

  • id (str, optional) – Element identifier for state binding

  • checked (bool, optional) – Initial checked state (default: False)

  • label (str, optional) – Label for single mode, displayed after switch

  • on_label (str, optional) – Label shown for “on” state in dual mode (default: “ON”)

  • off_label (str, optional) – Label shown for “off” state in dual mode (default: “OFF”)

  • label_mode ({"single", "dual"}, optional) – Label display mode (default: “single”)

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

  • tab_index (int | None)

  • bind (bool | str)

Variables:

  • checked (bool) – Current checked state

  • label (str or None) – Label text (single mode)

  • on_label (str) – On state label (dual mode)

  • off_label (str) – Off state label (dual mode)

  • label_mode (str) – Label display mode

  • on_change (callable or None) – Callback (old_value, new_value) when the checked state changes

  • on_action (callable or None) – Callback when the toggle is activated (space/enter/click)

  • action (str or None) – Action ID to dispatch (set by template extension)

  • bind (bool) – Whether to auto-bind to state[id] (default: True)

Notes

Keyboard controls: - Space/Enter: Toggle the switch

Mouse controls: - Click: Toggle the switch

Visual representation (Unicode): - Single mode (off): Gray track with knob on right + Label - Single mode (on): Green track with knob on left + Label - Dual mode: OFF/ON labels on sides with colored switch

Visual representation (ASCII): - Off: [ O] or OFF [ O] ON - On: [O ] or OFF [O ] ON

__init__(id=None, classes=None, tab_index=None, checked=False, label=None, on_label='ON', off_label='OFF', label_mode='single', bind=True)[source]
Parameters:
Return type:

None

Methods

__init__([id, classes, tab_index, checked, ...])

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 that should survive 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 toggle.

handle_key(key)

Handle keyboard input.

handle_mouse(event)

Handle mouse click to toggle.

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 toggle switch to paint context.

restore_ephemeral_state(state)

Restore ephemeral state after reconciliation.

set_bounds(bounds)

Set the element's screen bounds.

toggle()

Toggle the current state.

toggle_class(class_name)

Toggle a CSS class on this element.

Attributes

FOCUS_COLOR

KNOB_CHAR

KNOB_CHAR_ASCII

OFF_COLOR

ON_COLOR

TRACK_CHAR

TRACK_CHAR_ASCII

captures_tab

Whether this element wants the Tab key instead of focus movement.

checked

Get checked state.

parent_frame

Get the parent Frame if this element is inside a scrollable frame.

supports_dynamic_sizing

Whether this element supports dynamic sizing.
TRACK_CHAR = '░'
KNOB_CHAR = '█'
TRACK_CHAR_ASCII = '-'
KNOB_CHAR_ASCII = 'O'
ON_COLOR = (0, 200, 0)
OFF_COLOR = (100, 100, 100)
FOCUS_COLOR = (0, 255, 255)
property checked: bool

Get checked state.

Returns:

Current checked state

Return type:

bool

toggle()[source]

Toggle the current state.

Flips the checked state (which fires on_change) and then fires on_action.

Return type:

None

render_signature()[source]

Paint memo for the skip-unchanged fast path.

Captures the label mode and the three label strings; the knob position, track color, and active-label choice all follow from checked/focused (folded into _style_signature()). See wijjit.elements.base.Element.render_signature().

Return type:

Any

render_to(ctx)[source]

Render toggle switch to paint context.

Parameters:

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

  • styles (Theme)

  • colors (This element uses the following theme style classes for)

  • toggle.on (-)

  • toggle.off (-)

  • toggle:focus (-)

  • toggle.label (-)

  • toggle.label.active (-)

  • toggle.label.inactive (-)

  • colors:: (Example CSS to customize) – toggle.on { color: rgb(0, 255, 0); } toggle.off { color: rgb(255, 0, 0); }

Return type:

None

get_intrinsic_size()[source]

Get the intrinsic (preferred) size of the toggle.

Returns:

(width, height) based on mode and labels

Return type:

tuple[int, int]

handle_key(key)[source]

Handle keyboard input.

Parameters:

key (Key) – Key press to handle

Returns:

True if key was handled

Return type:

bool

async handle_mouse(event)[source]

Handle mouse click to toggle.

Parameters:

event (MouseEvent) – Mouse event to handle

Returns:

True if event was handled

Return type:

bool