- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
import { LoaderIcon } from "lucide-react";
import { cn } from "@/lib/utils";
function Spinner({
className,
variant = "default",
borderWidth,
...props
}: React.ComponentProps<"span"> & {
variant?: "default" | "spoke";
borderWidth?: number;
}) {
if (variant === "spoke") {
return (
<span
aria-label="Loading"
className={cn(
"inline-flex size-4 shrink-0 items-center justify-center",
className
)}
data-slot="spinner"
data-variant="spoke"
role="status"
{...props}
>
<span className="block size-full [transform-origin:center] animate-spin [transform-box:view-box] motion-reduce:animate-none">
<LoaderIcon className="block size-full [shape-rendering:geometricPrecision]" />
</span>
</span>
);
}
return (
<span
aria-label="Loading"
className={cn(
"inline-block size-4 shrink-0 animate-spin rounded-full border-current border-t-transparent motion-reduce:animate-none",
borderWidth === undefined ? "border-2" : "",
className
)}
data-slot="spinner"
data-variant="default"
role="status"
style={
borderWidth === undefined
? undefined
: { borderWidth: `${borderWidth}px` }
}
{...props}
/>
);
}
export { Spinner };Spinner renders a loading indicator. It carries role="status" and aria-label="Loading" so screen readers announce a live state. Two shapes are available: default (a circular arc, rendered as CSS border for zero rotation jitter) and spoke (a sunburst, from LoaderIcon).
Installation
$ bunx --bun frakment add spinner$ npx frakment add spinner$ pnpm dlx frakment add spinner$ yarn dlx frakment add spinner
Install the following dependency:
$ bun add lucide-react$ npm install lucide-react$ pnpm add lucide-react$ yarn add lucide-react
Copy and paste the following code into your project.
import { LoaderIcon } from "lucide-react";
import { cn } from "@/lib/utils";
function Spinner({
className,
variant = "default",
borderWidth,
...props
}: React.ComponentProps<"span"> & {
variant?: "default" | "spoke";
borderWidth?: number;
}) {
if (variant === "spoke") {
return (
<span
aria-label="Loading"
className={cn(
"inline-flex size-4 shrink-0 items-center justify-center",
className
)}
data-slot="spinner"
data-variant="spoke"
role="status"
{...props}
>
<span className="block size-full [transform-origin:center] animate-spin [transform-box:view-box] motion-reduce:animate-none">
<LoaderIcon className="block size-full [shape-rendering:geometricPrecision]" />
</span>
</span>
);
}
return (
<span
aria-label="Loading"
className={cn(
"inline-block size-4 shrink-0 animate-spin rounded-full border-current border-t-transparent motion-reduce:animate-none",
borderWidth === undefined ? "border-2" : "",
className
)}
data-slot="spinner"
data-variant="default"
role="status"
style={
borderWidth === undefined
? undefined
: { borderWidth: `${borderWidth}px` }
}
{...props}
/>
);
}
export { Spinner };Update the import paths to match your project setup.
Usage
import { Spinner } from "@/components/ui/spinner";<Spinner />Examples
Shapes
default renders a circular arc. spoke renders a sunburst from LoaderIcon.
import { Spinner } from "@/components/ui/spinner";
export function SpinnerShapes() {
return (
<div className="flex flex-wrap items-center gap-8">
<div className="flex flex-col items-center gap-2">
<Spinner className="size-6" />
<span className="text-muted-foreground text-xs">default</span>
</div>
<div className="flex flex-col items-center gap-2">
<Spinner className="size-6" variant="spoke" />
<span className="text-muted-foreground text-xs">spoke</span>
</div>
</div>
);
}Size
Use a size-* utility class to change the diameter. Default is 16px (size-4).
import { Spinner } from "@/components/ui/spinner";
export function SpinnerSize() {
return (
<div className="flex items-center gap-6">
<Spinner className="size-3" />
<Spinner className="size-4" />
<Spinner className="size-6" />
<Spinner className="size-8" />
</div>
);
}Button
Place the spinner before the label with data-icon="inline-start", or after with data-icon="inline-end". The button uses the attribute for gap spacing.
import { Button } from "@/components/ui/button";
import { Spinner } from "@/components/ui/spinner";
export function SpinnerButton() {
return (
<div className="flex flex-wrap items-center gap-3">
<Button disabled>
<Spinner data-icon="inline-start" />
Processing
</Button>
<Button disabled variant="outline">
<Spinner data-icon="inline-start" />
Saving
</Button>
<Button disabled variant="secondary">
Loading
<Spinner data-icon="inline-end" />
</Button>
</div>
);
}Badge
Same idea inside a badge — data-icon keeps the gap aligned with the badge icon size.
import { Badge } from "@/components/ui/badge";
import { Spinner } from "@/components/ui/spinner";
export function SpinnerBadge() {
return (
<div className="flex flex-wrap items-center gap-2">
<Badge>
<Spinner data-icon="inline-start" />
Syncing
</Badge>
<Badge variant="secondary">
<Spinner data-icon="inline-start" />
Updating
</Badge>
<Badge variant="outline">
Processing
<Spinner data-icon="inline-end" />
</Badge>
</div>
);
}In context
Combine with a shimmer text for a live streaming line.
import { Spinner } from "@/components/ui/spinner";
export function SpinnerInContext() {
return (
<div className="w-full max-w-sm py-4">
<div className="text-muted-foreground mx-auto flex w-fit items-center gap-2 text-sm">
<Spinner />
<span className="shimmer">Thinking…</span>
</div>
</div>
);
}API Reference
Spinner
| Prop | Type | Default | Description |
|---|---|---|---|
variant | defaultspoke | — | Icon shape — circular arc (default) or sunburst (spoke). |
borderWidth | number | — | Custom border thickness for the default variant. Defaults to Tailwind border-2. |
Extends React.ComponentProps<"span">. Defaults: size-4, animate-spin, role="status", aria-label="Loading".
Accessibility
- Renders
role="status"andaria-label="Loading"by default — screen readers treat it as a live region. - Pair with visible text for clarity when the loading state has semantic meaning.
animate-spinrespectsprefers-reduced-motionviamotion-reduce:animate-none.- When placed inside
ButtonorBadge, keepdata-icon="inline-start"or"inline-end"so the gap matches the surrounding component.
Best Practices
- Pair with text. A spinner alone is ambiguous.
- Do not block the whole page. Use a skeleton for content areas.
- Respect reduced motion. When
prefers-reduced-motionis set, the icon renders static. - Hide after success. A lingering spinner reads as "still loading".