ki-spinner
@kimen/elements/ki-spinner- Source
- Agent reference
Use a spinner for a brief wait beside the affected content. Choose a ring for work such as saving or running a tool. Use typing dots for an assistant that is thinking. Use ki-progress for page-level work or a task with a known completed fraction.
Ring
The ring defaults to medium (20 px). Use size="sm" for 16 px or size="lg"
for 32 px at the default root font size. Set show-label to show the activity
name next to the ring.
<ki-spinner size="sm" label="Saving changes…" show-label></ki-spinner>Typing dots
Typing dots keep the same dimensions at every size.
<ki-spinner variant="dots" label="Assistant is thinking" show-label></ki-spinner>Accessibility
Set a localized label describing the activity. The label names the polite
status region in both variants. Insert the spinner at the start of an operation
to deliver the status update, then remove it when the operation ends. With
reduced motion, the ring rotates more slowly and the three dots stay still.
The spinner adds no tab stop.
API reference
When to use: show brief inline activity such as saving a change or running a tool. Choose typing dots for an assistant that is thinking. Set a localized label that names the activity and mount the spinner when the wait starts.
When not to use: use ki-progress for page-level work or a known fraction of a task. Use ki-alert for persistent notices.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
label | label | string | – | Localized name of the ongoing activity, such as "Saving changes". Supply a meaningful label for every spinner, even when the text is hidden. Use the activity's name whenever it can be more specific than "Loading". |
show-label | showLabel | boolean | false | Display the label beside the graphic when sighted users also need the activity description. The same text names the status in either case. |
size | size | "lg" | "md" | "sm" | 'md' | Diameter of the ring. Choose the size that fits the surrounding content. Dots use a fixed size. Unrecognized values draw the medium ring. |
variant | variant | "dots" | "ring" | 'ring' | Use a ring for general inline activity and dots for assistant typing or thinking. Unrecognized values draw a ring. |
CSS parts
| Part | Description |
|---|---|
dots | Group of three animated dots, in the dots variant. |
label | Activity text, adjacent to the graphic when show-label is set. |
ring | Rotating ring with a track and indicator, in the ring variant. |
CSS custom properties
The public styling contract of ki-spinner: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-spinner-dot-delay | Delay between consecutive typing dots. |
--ki-spinner-dot-duration | Typing pulse period. |
--ki-spinner-dot-easing | Easing of the typing pulse. |
--ki-spinner-dot-gap | Gap between dots. |
--ki-spinner-dot-scale-min | Smallest scale of a dot during the pulse. |
--ki-spinner-dot-size | Diameter of each dot at full size. |
--ki-spinner-indicator | Ink of the revolving ring segment. |
--ki-spinner-label-bg | Background of the inline activity label. |
--ki-spinner-label-fg | Ink of the visible label and the typing dots. |
--ki-spinner-label-font-family | Font family of the visible label. |
--ki-spinner-label-font-size | Font size of the visible label. |
--ki-spinner-label-gap | Gap between the graphic and the visible label. |
--ki-spinner-label-line-height | Line height of the visible label. |
--ki-spinner-radius | Round corners of the ring and dots. |
--ki-spinner-ring-duration | Standard ring rotation period. |
--ki-spinner-ring-duration-reduced | Ring rotation period when reduced motion is requested. |
--ki-spinner-ring-easing | Easing for ring rotation. |
--ki-spinner-size | Default ring diameter. |
--ki-spinner-size-lg | Large ring diameter. |
--ki-spinner-size-sm | Small ring diameter. |
--ki-spinner-stroke | Stroke width of the small and medium rings. |
--ki-spinner-stroke-lg | Stroke width of the large ring. |
--ki-spinner-track | Ink of the ring track. |
--ki-typography-family-body | semantic font family for typography family body. |