wijjit.elements.display.spinner.Spinner

class wijjit.elements.display.spinner.Spinner(id=None, classes=None, active=True, style='dots', label='', color=None, frame_index=0, bind=True)[source]

Spinner element for displaying indefinite loading animation.

This element provides an animated spinner indicator with support for: - Multiple animation styles (dots, line, bouncing, clock) - Unicode detection with ASCII fallback - Optional label text - Optional coloring - Active/inactive state control

Parameters:

id (str, optional) – Element identifier
active (bool, optional) – Whether spinner is active and animating (default: True)
style (str, optional) – Animation style: “dots”, “line”, “bouncing”, “clock” (default: “dots”)
label (str, optional) – Label text to display next to spinner (default: “”)
color (str, optional) – Foreground color for the spinner glyph, on top of the theme style. Accepts a named color, #RRGGBB hex, or rgb(r, g, b) (default: None, use the theme color).
frame_index (int, optional) – Current animation frame index (default: 0)
classes (str | list[str] | set[str] | None)
bind (bool | str)

Variables:

active (bool) – Whether spinner is active
style (str) – Animation style
label (str) – Label text
color (str or None) – Color name
frame_index (int) – Current frame index

__init__(id=None, classes=None, active=True, style='dots', label='', color=None, frame_index=0, bind=True)[source]

Parameters:

id (str | None)
classes (str | list[str] | set[str] | None)
active (bool)
style (Literal['dots', 'line', 'bouncing', 'clock'])
label (str)
color (str | None)
frame_index (int)
bind (bool | str)

Return type:

None

Methods

`__init__`([id, classes, active, style, ...])
`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 size of the spinner.
`handle_key`(key)	Handle a key press.
`handle_mouse`(event)	Handle a mouse event.
`has_class`(class_name)	Check if element has a CSS class.
`next_frame`()	Advance to the next animation frame.
`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 spinner 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.
`parent_frame`	Get the parent Frame if this element is inside a scrollable frame.
`supports_dynamic_sizing`	Whether this element supports dynamic sizing.

next_frame()[source]

Advance to the next animation frame.

This method increments the frame index and wraps around to 0 when reaching the end of the animation sequence.

Return type:: None

get_intrinsic_size()[source]

Get the intrinsic size of the spinner.

Returns the total width including frame character and label. Always returns the maximum size (active case) to ensure proper clearing when spinner becomes inactive.

Returns:: (width, height) tuple
Return type:: tuple[int, int]

render_to(ctx)[source]

Render the spinner 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 supports all spinner animation styles and automatically handles Unicode detection with ASCII fallback.

Theme styles:

This element uses the following theme style classes: - spinner: Base spinner style (inactive) - spinner.active: Active/animating spinner style - spinner.text: Label text style