Skip to content
Kimenpre-v1documentation home
Color scheme

ki-spinner

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.

Theme for this example
Color scheme for this example
<ki-spinner size="sm" label="Saving changes…" show-label></ki-spinner>

Typing dots

Typing dots keep the same dimensions at every size.

Theme for this example
Color scheme for this example
<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

AttributePropertyTypeDefaultDescription
labellabelstring–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-labelshowLabelbooleanfalseDisplay the label beside the graphic when sighted users also need the activity description. The same text names the status in either case.
sizesize"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.
variantvariant"dots" | "ring"'ring'Use a ring for general inline activity and dots for assistant typing or thinking. Unrecognized values draw a ring.

CSS parts

PartDescription
dotsGroup of three animated dots, in the dots variant.
labelActivity text, adjacent to the graphic when show-label is set.
ringRotating 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.

TokenDescription
--ki-spinner-dot-delayDelay between consecutive typing dots.
--ki-spinner-dot-durationTyping pulse period.
--ki-spinner-dot-easingEasing of the typing pulse.
--ki-spinner-dot-gapGap between dots.
--ki-spinner-dot-scale-minSmallest scale of a dot during the pulse.
--ki-spinner-dot-sizeDiameter of each dot at full size.
--ki-spinner-indicatorInk of the revolving ring segment.
--ki-spinner-label-bgBackground of the inline activity label.
--ki-spinner-label-fgInk of the visible label and the typing dots.
--ki-spinner-label-font-familyFont family of the visible label.
--ki-spinner-label-font-sizeFont size of the visible label.
--ki-spinner-label-gapGap between the graphic and the visible label.
--ki-spinner-label-line-heightLine height of the visible label.
--ki-spinner-radiusRound corners of the ring and dots.
--ki-spinner-ring-durationStandard ring rotation period.
--ki-spinner-ring-duration-reducedRing rotation period when reduced motion is requested.
--ki-spinner-ring-easingEasing for ring rotation.
--ki-spinner-sizeDefault ring diameter.
--ki-spinner-size-lgLarge ring diameter.
--ki-spinner-size-smSmall ring diameter.
--ki-spinner-strokeStroke width of the small and medium rings.
--ki-spinner-stroke-lgStroke width of the large ring.
--ki-spinner-trackInk of the ring track.
--ki-typography-family-bodysemantic font family for typography family body.

Workshop

Open ki-spinner in Storybook