Basel Standard / Docs

Spinner

Inline loading indicator for short-lived background work and pending actions.

Loading release metrics

Use the spinner when the interface is actively working and the result is expected soon. The Swiss wrapper keeps the motion small, neutral, and easy to place inside buttons, status rows, and compact operational surfaces without turning loading state into decoration.

Installation

Install

Purchase access, then open /account/install to issue a registry token.

Usage

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

<Spinner />
<Spinner size="sm" />

Why This Primitive Exists

Loading feedback should confirm progress without competing with the surrounding task.

Use it for short waits: pending requests, saving states, or local refresh work.
Keep it adjacent to the label or action it explains.
Avoid using it as a page filler when a skeleton, empty state, or staged layout would communicate more clearly.

Examples

Basic Indicator

The smallest useful pattern is a spinner next to a plain status label.

Loading release metrics

<div className="flex items-center gap-3">
  <Spinner />
  <span>Loading release metrics</span>
</div>

Size Variants

Use the smallest size that still reads clearly in context. Larger indicators are better for panel-level loading states, not for inline labels.

Small

Default

Large

<Spinner size="sm" />
<Spinner size="default" />
<Spinner size="lg" />

In Context

Pair the spinner with the task name and any useful progress detail. The component works best when the user can tell what is still pending.

Background work

Use the spinner to confirm work is in progress, not to fill dead space.

Keep the indicator close to the task label so users know what is still loading.

Syncing inventory snapshot

Updating 148 product records.

Guidance

Keep The Signal Local

Place the spinner near the button, row, or module that is currently working.
Add nearby text when the loading reason is not obvious from the layout alone.
Remove it as soon as the state resolves instead of leaving a generic busy indicator on screen.

Match The Weight To The Delay

Use the spinner for short-lived loading states and optimistic save work.
Use skeletons when the page structure is not ready yet.
Use progress components when the work has measurable stages or percent completion.

Avoid Decorative Motion

Do not scatter several spinners across one surface.
Do not enlarge the icon to compensate for unclear status copy.
Keep the indicator neutral so the content and task state remain primary.

API Reference

Spinner

Spinner renders the lucide-react LoaderCircle icon with the repo's default spin animation and accepts the icon's standard SVG props except for the built-in size prop.

Prop	Type	Default
`size`	`"sm" \| "default" \| "lg"`	`"default"`
`className`	`string`	`undefined`
`strokeWidth`	`number`	Lucide default

Exported Helper

Export	Type	Notes
`spinnerVariants`	CVA helper	Returns the class set for the available size variants.

All other Lucide SVG props such as aria-hidden, role, stroke, and style pass through unchanged.

Previous: Sonner Next: Switch