Skip to content
Browse documentation
whisk/ui

Spinner

Show that a local operation is in progress.

Overview

Spinner is a labelled, indeterminate status indicator for work with no meaningful completion value. The application decides when the work starts and removes the Spinner when it ends.

Use when

A local operation is active and no measurable completion value is available.

Use instead

Use Progress when you know the current amount and total.

Usage

Saving changes
import { Spinner } from "@smoothie-framework/whisk-react";

<Spinner label="Saving changes" />

Examples

Choose a local size

Keep a Spinner proportional to the surface it represents. Size changes the visual ring, not the status semantics.

Loading activityLoading activityLoading activityLoading activityLoading activity
import { Spinner, StackRow } from "@smoothie-framework/whisk-react";

<StackRow align="center" gap={4}>
  <Spinner size="xs" label="Loading activity" />
  <Spinner size="sm" label="Loading activity" />
  <Spinner size="md" label="Loading activity" />
  <Spinner size="lg" label="Loading activity" />
  <Spinner size="xl" label="Loading activity" />
</StackRow>

Name the work beside a decorative spinner

When visible text already communicates the status, hide the duplicate Spinner from assistive technology.

Saving changes

import { Spinner, StackRow, Text } from "@smoothie-framework/whisk-react";

<StackRow align="center" gap={2}>
  <Spinner aria-hidden="true" label="Saving changes" size="sm" />
  <Text>Saving changes</Text>
</StackRow>

Use button loading for a submitted action

Button already has loading behavior and renders its Spinner as decorative. Do not add a second standalone Spinner to a loading button.

import { Button } from "@smoothie-framework/whisk-react";

<Button loading loadingText="Saving">
  Save changes
</Button>

Adjust the ring within a local surface

Use theme tokens first. These props set scoped CSS variables when a component needs a local visual adjustment.

Syncing project
import { Spinner } from "@smoothie-framework/whisk-react";

<Spinner
  label="Syncing project"
  color="accent"
  trackColor="surface3"
  borderWidth={3}
  animationDuration="1.2s"
/>

Use a measurable indicator for known progress

Spinner cannot show a fraction complete. Switch to Progress when the application knows a value and maximum.

3 of 5 files uploaded
import { Progress } from "@smoothie-framework/whisk-react";

<Progress value={3} max={5} showLabel valueText="3 of 5 files uploaded" />

Props

Component props

PropTypeDefaultDescription
sizexs | sm | md | lg | xlmdChoose the visual size. Spinner does not accept responsive size objects.
labelstringLoading...Provide non-empty status text. It names the status and remains available when motion is reduced.
colorColorToken | CSS named colorsurfaceInverseSet the rotating arc color with a theme token or CSS named color.
trackColorColorToken | CSS named colorsurfaceInverseAlpha32Set the static track color with a theme token or CSS named color.
borderWidthnumber | CSS lengththeme defaultSet the ring thickness. A number is interpreted as pixels.
animationDurationCSS time string800msSet one rotation duration, such as 1.2s. A number is not valid.
className | style | native span attributesnative attributesnoneForward styling and ordinary native span attributes to the root. role, aria-label, and aria-live are owned by Spinner.

Accessibility

Spinner renders a span with role=status, aria-live=polite, and an accessible name taken from label. Its visually hidden label remains available when reduced-motion CSS stops the rotation. Do not override those semantics or rely on the animation alone. Give label a specific operation name, such as Saving changes, rather than Loading when the work is known. Pass aria-hidden=true only when nearby text already communicates the same pending status; otherwise it would hide the only status. Spinner does not move focus, capture keyboard input, track a request, or announce success or failure after it unmounts. Keep a result message in the page, use Alert when it must remain in context, and use Progress when a known value and maximum can describe completion.

Content guidance

The label should describe the active work, such as Saving workspace. Avoid vague labels such as Loading when the operation is known.