Spinner
SaveA small loading indicator in four sizes, as a quarter arc or a stepping ring of dots, with an accessible label that can also be shown as text.
- Category
- Feedback
- Version
- 0.1.0
- Frameworks
- Next.js, Vite + React
- Styling
- Tailwind CSS v4
Preview
Spinner preview
Arc
Loading, xsLoading, smLoading, mdLoading, lg
DotsLoading, xsLoading, smLoading, mdLoading, lg
acme/webSyncing 24 files
acme/apiIndexing
Installation
npx @shakenui/cli add spinnerReview the plan first. A dry run lists every file and package without changing anything:
npx @shakenui/cli add spinner --dry-runUsage
spinner-example.tsx
import { Spinner } from "@/components/shaken/ui/spinner";
const sizes = ["xs", "sm", "md", "lg"] as const;
export default function SpinnerExample() {
return (
<div className="grid w-full max-w-md gap-8">
<div className="grid grid-cols-[auto_1fr] items-center gap-x-6 gap-y-5">
<span className="text-xs font-medium text-zinc-500">Arc</span>
<div className="flex items-center gap-5">
{sizes.map((size) => (
<Spinner key={size} size={size} label={`Loading, ${size}`} />
))}
</div>
<span className="text-xs font-medium text-zinc-500">Dots</span>
<div className="flex items-center gap-5">
{sizes.map((size) => (
<Spinner key={size} size={size} variant="dots" label={`Loading, ${size}`} />
))}
</div>
</div>
<div className="divide-y divide-zinc-950/[0.07] rounded-xl border border-zinc-950/10 dark:divide-white/[0.08] dark:border-white/10">
<div className="flex items-center justify-between gap-4 px-4 py-3 text-sm">
<span className="text-zinc-950 dark:text-white">acme/web</span>
<Spinner showLabel label="Syncing 24 files" />
</div>
<div className="flex items-center justify-between gap-4 px-4 py-3 text-sm">
<span className="text-zinc-950 dark:text-white">acme/api</span>
<Spinner showLabel variant="dots" label="Indexing" />
</div>
</div>
</div>
);
}API
| Prop | Type | Default | Description |
|---|---|---|---|
| size | "xs" | "sm" | "md" | "lg" | "sm" | 12, 16, 20, or 24px. |
| variant | "arc" | "dots" | "arc" | arc is the quarter arc on a faint track used by Button; dots is a ring of eight dots whose brightest dot steps around it. |
| label | ReactNode | "Loading" | What is loading. Read by screen readers, and shown beside the spinner with showLabel. |
| showLabel | boolean | false | Shows the label as secondary text beside the spinner. |
| decorative | boolean | false | Hides the spinner from assistive technology when the surrounding element already reports that it is busy. |
Accessibility
- Renders a polite status region (role="status") named by its label text, which is visually hidden unless showLabel is set.
- decorative sets aria-hidden for spinners inside elements that already announce busy state, such as a button with aria-busy.
- The SVG marks are aria-hidden; only the label is read.
- The rotation runs only with motion-safe; under reduced motion both variants render a still frame.
Files
Installed into src/components/shaken, or components/shaken when the project has no src directory.
src/components/shaken/ui/spinner.tsxspinner- npm packages: noneReact and Tailwind CSS v4 required
Source
The exact source the CLI installs, from /r/items/react/spinner/0.1.0.json.
ui/spinner.tsxShowHide
ui/spinner.tsx
import type { ComponentProps, ReactNode } from "react";
function cx(...classes: (string | false | null | undefined)[]) {
return classes.filter(Boolean).join(" ");
}
const sizes = {
xs: { box: "size-3", text: "text-xs", gap: "gap-1.5" },
sm: { box: "size-4", text: "text-sm", gap: "gap-2" },
md: { box: "size-5", text: "text-sm", gap: "gap-2" },
lg: { box: "size-6", text: "text-[15px]", gap: "gap-2.5" },
} as const;
export type SpinnerSize = keyof typeof sizes;
export interface SpinnerProps extends Omit<ComponentProps<"span">, "children" | "role"> {
/** 12, 16, 20, or 24px. */
size?: SpinnerSize;
/**
* `arc` is the quarter arc on a faint track, the same one Button uses while loading.
* `dots` is a ring of eight dots whose brightest dot steps around, in the dot language of the agent marks.
*/
variant?: "arc" | "dots";
/** What is loading. Read by screen readers, and shown next to the spinner with `showLabel`. */
label?: ReactNode;
/** Shows the label as text beside the spinner instead of only to screen readers. */
showLabel?: boolean;
/**
* Hides the spinner from assistive technology, for when the surrounding element already
* says it is busy (a button with `aria-busy`, a region with its own status text).
*/
decorative?: boolean;
}
/**
* A small loading indicator. It is a polite status region named by `label`, unless `decorative`.
* The rotation is the one loop DESIGN.md allows; with reduced motion it holds still.
*/
export function Spinner({
size = "sm",
variant = "arc",
label = "Loading",
showLabel = false,
decorative = false,
className,
...props
}: SpinnerProps) {
const config = sizes[size];
return (
<span
role={decorative ? undefined : "status"}
aria-hidden={decorative || undefined}
data-variant={variant}
className={cx(
"inline-flex shrink-0 items-center align-middle text-zinc-950 dark:text-white",
showLabel && config.gap,
className,
)}
{...props}
>
{variant === "dots" ? <DotsMark className={config.box} /> : <ArcMark className={config.box} />}
{decorative ? null : showLabel ? (
<span className={cx("leading-5 text-zinc-600 dark:text-zinc-400", config.text)}>{label}</span>
) : (
<span className="sr-only">{label}</span>
)}
</span>
);
}
function ArcMark({ className }: { className: string }) {
return (
<svg aria-hidden="true" viewBox="0 0 16 16" fill="none" className={cx("motion-safe:animate-spin", className)}>
<circle cx="8" cy="8" r="6" stroke="currentColor" strokeOpacity="0.2" strokeWidth="1.5" />
<path d="M14 8a6 6 0 0 0-6-6" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
</svg>
);
}
// Brightest first, then a fading tail behind it in the direction of travel.
const tail = [1, 0.78, 0.6, 0.46, 0.35, 0.27, 0.21, 0.17];
function DotsMark({ className }: { className: string }) {
return (
<svg
aria-hidden="true"
viewBox="0 0 16 16"
fill="currentColor"
// Eight discrete steps per turn: the lit dot hops from position to position instead of
// smearing, so the ring reads as dots even at 12px.
className={cx("motion-safe:animate-spin motion-safe:[animation-duration:0.96s] motion-safe:[animation-timing-function:steps(8,end)]", className)}
>
{tail.map((opacity, i) => {
// Counter-clockwise from the top, so the bright dot leads a clockwise turn.
const angle = -Math.PI / 2 - (i * Math.PI) / 4;
return (
<circle
key={i}
cx={(8 + Math.cos(angle) * 5.6).toFixed(2)}
cy={(8 + Math.sin(angle) * 5.6).toFixed(2)}
r={i === 0 ? 1.45 : 1.25}
opacity={opacity}
/>
);
})}
</svg>
);
}