Skip to content

Design system

Documentation

DesignComponents / Spinner

Components / Spinner

Beta

Spinner

Show that a local operation is still working.

On this page

Examples

Local loading status

Use the spinner beside or inside the content that is waiting.

Loading a previewLoading a reportLoading workspace data

Three spinner sizes with screen-reader status text

Bounded overlay

Overlay mode covers a positioned parent; its content remains in the document and scrolls only when the parent requires it.

Report contentLoading report

Spinner overlay in a positioned content surface

Try the props

Compare the shared icon sizes and optional parent overlay.

Loading report

Spinner property playground

When to use

Use Spinner when work is underway but its completion amount is not useful or known. Use Progress when the completed amount can be measured. Overlay mode is bounded to a positioned parent and does not perform any data work.

Usage

import { Spinner } from "@phuctech/ui/components/spinner";

<Spinner label="Loading report" />

API

Component API
PropTypeDefaultDescriptionConstraints
labelstring"Loading"Status text available to assistive technology.Describe the operation when several tasks can load at once.
size"sm" | "md" | "lg""md"Spinner diameter from the shared icon scale.Keep the status near the content that is waiting.
overlaybooleanfalseAbsolutely covers the nearest positioned parent.The parent must establish positioning and a bounded area.
classNamestring—Additional classes on the status root.The root remains an inline status unless overlay is enabled.

Tokens

Component tokens
TokenRoleEffective valueUsage
--size-icon-md / --size-icon-lg / --size-icon-xlSpinner diametersm / md / lgUses the same scale as shared icons.
--color-action-primaryIndicatorBrand foregroundMaintains contrast in the current theme.
prefers-reduced-motionMotion preferenceStatic ringThe status label remains while rotation stops.

Accessibility

  • The root has a polite status role and includes a screen-reader label.
  • Reduced-motion users receive a static indicator with the same status text.

Do and don’t

Do

Place the indicator beside the affected task and explain its status.

Don’t

Use Spinner to estimate completion or to cover an unbounded page.

  • Progress shows measurable completion.
  • Skeleton reserves the shape of content during the initial load.