Spinner

Loading your workspace…

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

export default function SpinnerDemo() {
  return (
    <div className="flex items-center gap-2 text-muted-foreground text-sm">
      <Spinner aria-hidden />
      Loading your workspace…
    </div>
  );
}

Installation

$ pnpm dlx shadcn@latest add @desyne/spinner

The CLI installs dependencies and any other components this one uses.

Usage

tsx

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

tsx

<Spinner label="Loading invoices" />

Buttons have their own spinner

For a button that is working, use Button's isPending prop instead of placing a Spinner inside it. It shows a spinner, blocks presses and announces the busy state for you.

When to use

Spinner — a short wait (roughly under a few seconds) with no measurable progress, in a small space: inline text, badges, list footers, a refreshing panel.
Skeleton — when you know the shape of the content that's loading; it avoids layout shift.
Progress Bar — when you can measure progress, or the wait is long enough that users need to know how far along it is.
Toast with toast.promise — for background work the user shouldn't wait on.

Anatomy

A spinner is a single element: a bordered circle with one transparent side, rotating.

tsx

<Spinner />   {/* <span role="status" aria-label="Loading"> */}

Part	Renders	Notes
`Spinner`	`<span role="status">`	Root. `border-current` with a transparent right edge, `animate-spin` (`animate-pulse` under reduced motion). Carries `data-slot="spinner"`.

Examples

Sizes

sm (16px) is the default and matches body text. xs (12px) fits badges and small buttons, md (20px) suits headings and toolbars, and lg (32px) is for panels and page-level loading.

xs

sm

md

lg

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

export default function SpinnerSizes() {
  return (
    <div className="flex items-end gap-8">
      {(["xs", "sm", "md", "lg"] as const).map((size) => (
        <div key={size} className="flex flex-col items-center gap-2">
          <Spinner size={size} />
          <code className="text-muted-foreground text-xs">{size}</code>
        </div>
      ))}
    </div>
  );
}

Colors

Without color, the spinner uses the current text color, so it blends into whatever it's placed in. Pass a tone to give it its own color.

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

export default function SpinnerColors() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      <span className="text-muted-foreground">
        <Spinner size="md" />
      </span>
      <Spinner size="md" color="primary" />
      <Spinner size="md" color="brand" />
      <Spinner size="md" color="info" />
      <Spinner size="md" color="success" />
      <Spinner size="md" color="warning" />
      <Spinner size="md" color="danger" />
    </div>
  );
}

Custom size

For sizes outside the scale, set size-* and a matching border width with className. Tailwind's arbitrary properties can also slow the rotation.

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

export default function SpinnerCustomSize() {
  return (
    <div className="flex items-center gap-8">
      <Spinner className="size-12 border-4" color="brand" />
      <Spinner className="size-6 border-[1.5px] [animation-duration:1.5s]" />
    </div>
  );
}

label ("Loading" by default) becomes the accessible name. Make it specific when the spinner stands alone. When visible text next to it already says what's happening, pass aria-hidden so screen readers don't hear it twice.

Checking availability…

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

export default function SpinnerLabel() {
  return (
    <div className="flex flex-col items-center gap-4 text-sm">
      {/* Standalone: the label is the only description of what's happening. */}
      <Spinner size="md" label="Loading invoices" />

      {/* Next to visible text: hide the spinner so the text isn't doubled. */}
      <p className="flex items-center gap-2 text-muted-foreground">
        <Spinner aria-hidden /> Checking availability…
      </p>
    </div>
  );
}

In context

Spinners inherit the text color and don't shrink in flex rows, so they drop into badges and inline status text without extra styling.

Syncing Deploying

Loading results…

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

export default function SpinnerInContext() {
  return (
    <div className="flex flex-col items-center gap-4">
      <div className="flex gap-2">
        <Badge color="neutral">
          <Spinner size="xs" /> Syncing
        </Badge>
        <Badge color="info">
          <Spinner size="xs" /> Deploying
        </Badge>
      </div>
      <p className="flex items-center gap-2 text-muted-foreground text-sm">
        <Spinner size="sm" /> Loading results…
      </p>
    </div>
  );
}

Loading overlay

Cover stale content with a translucent layer and a centered spinner while it refreshes. Keep the old content visible underneath so the layout doesn't jump.

Exchange rates

USD → EUR: 0.9214
USD → GBP: 0.7862
USD → JPY: 156.31

import { useEffect, useState } from "react";
import { Button } from "@/components/ui/button";
import { Spinner } from "@/components/ui/spinner";

export default function SpinnerOverlay() {
  const [refreshing, setRefreshing] = useState(false);

  useEffect(() => {
    if (!refreshing) return;
    const timer = setTimeout(() => setRefreshing(false), 1500);
    return () => clearTimeout(timer);
  }, [refreshing]);

  return (
    <div className="flex w-full max-w-sm flex-col gap-3">
      <div
        aria-busy={refreshing}
        className="relative overflow-hidden rounded-xl border bg-card p-4"
      >
        <p className="font-medium text-sm">Exchange rates</p>
        <dl className="mt-3 grid grid-cols-2 gap-y-1.5 text-sm">
          <dt className="text-muted-foreground">USD → EUR</dt>
          <dd className="text-right tabular-nums">0.9214</dd>
          <dt className="text-muted-foreground">USD → GBP</dt>
          <dd className="text-right tabular-nums">0.7862</dd>
          <dt className="text-muted-foreground">USD → JPY</dt>
          <dd className="text-right tabular-nums">156.31</dd>
        </dl>
        {refreshing && (
          <div className="absolute inset-0 flex items-center justify-center bg-card/70 backdrop-blur-[1px]">
            <Spinner size="lg" color="brand" label="Refreshing rates" />
          </div>
        )}
      </div>
      <Button
        size="sm"
        variant="outline"
        className="self-start"
        isDisabled={refreshing}
        onPress={() => setRefreshing(true)}
      >
        Refresh
      </Button>
    </div>
  );
}

Recipes

Deploy steps

A step list where the running step shows a spinner and finished steps show a check. A visually hidden live region announces each step, since the spinners are hidden from screen readers.

Deploying acme-web

Cloning repository
Installing dependencies
Building application
Uploading assets
Assigning domain

import { CircleCheckIcon, CircleIcon } from "lucide-react";
import { useEffect, useState } from "react";
import { Button } from "@/components/ui/button";
import { Spinner } from "@/components/ui/spinner";
import { cn } from "@/lib/utils";

const steps = [
  "Cloning repository",
  "Installing dependencies",
  "Building application",
  "Uploading assets",
  "Assigning domain",
];

export default function SpinnerRecipeDeploySteps() {
  const [current, setCurrent] = useState(0);
  const done = current >= steps.length;

  useEffect(() => {
    if (done) return;
    const timer = setInterval(() => setCurrent((c) => c + 1), 1100);
    return () => clearInterval(timer);
  }, [done]);

  return (
    <div className="w-full max-w-sm rounded-xl border bg-card p-4">
      <div className="mb-3 flex items-center justify-between">
        <p className="font-medium text-sm">
          {done ? "Deployed to production" : "Deploying acme-web"}
        </p>
        <Button
          size="xs"
          variant="ghost"
          isDisabled={!done}
          onPress={() => setCurrent(0)}
        >
          Redeploy
        </Button>
      </div>
      <ol className="grid gap-2.5 text-sm">
        {steps.map((step, i) => (
          <li
            key={step}
            className={cn(
              "flex items-center gap-2.5",
              i > current && "text-muted-foreground",
            )}
          >
            {i < current && (
              <CircleCheckIcon className="size-4 text-success" aria-hidden />
            )}
            {i === current && <Spinner color="brand" aria-hidden />}
            {i > current && (
              <CircleIcon className="size-4 opacity-40" aria-hidden />
            )}
            {step}
          </li>
        ))}
      </ol>
      <p aria-live="polite" className="sr-only">
        {done ? "Deployment complete" : steps[current]}
      </p>
    </div>
  );
}

Load more

A list footer that swaps its button for a spinner and text while the next page loads.

Fix flaky checkout test
Add Slack alerts for failed deploys
Migrate billing to usage-based pricing

import { useState } from "react";
import { Button } from "@/components/ui/button";
import { Spinner } from "@/components/ui/spinner";

const all = [
  "Fix flaky checkout test",
  "Add Slack alerts for failed deploys",
  "Migrate billing to usage-based pricing",
  "Update onboarding copy",
  "Rotate staging database credentials",
  "Add CSV export to reports",
  "Improve search ranking for docs",
  "Drop support for Node 18",
  "Audit third-party scripts",
];

export default function SpinnerRecipeLoadMore() {
  const [count, setCount] = useState(3);
  const [loading, setLoading] = useState(false);
  const hasMore = count < all.length;

  async function loadMore() {
    setLoading(true);
    await new Promise((r) => setTimeout(r, 1000));
    setCount((c) => Math.min(all.length, c + 3));
    setLoading(false);
  }

  return (
    <div className="w-full max-w-sm rounded-xl border bg-card">
      <ul className="divide-y text-sm">
        {all.slice(0, count).map((title) => (
          <li key={title} className="px-4 py-2.5">
            {title}
          </li>
        ))}
      </ul>
      <div className="flex justify-center border-t p-2">
        {loading ? (
          <div className="flex h-7 items-center gap-2 text-muted-foreground text-xs">
            <Spinner size="xs" aria-hidden /> Loading more issues…
          </div>
        ) : hasMore ? (
          <Button size="sm" variant="ghost" onPress={loadMore}>
            Load more
          </Button>
        ) : (
          <p className="flex h-7 items-center text-muted-foreground text-xs">
            You're all caught up
          </p>
        )}
      </div>
    </div>
  );
}

Accessibility

Renders role="status" with aria-label set from label, so it's exposed as a named status element.
Give standalone spinners a specific label ("Loading invoices"). Next to visible text, pass aria-hidden instead.
A spinner that appears doesn't reliably announce itself. If completion matters, announce it with a live region or a toast, and set aria-busy on the region that is loading.
Respects prefers-reduced-motion: the ring stops rotating and fades gently in and out instead (motion-reduce:animate-pulse), so it still reads as "working" without movement. The role="status" label is announced either way. Add motion-reduce:animate-none to a spinner's className for a fully static ring.

Styling

Data slots

Slot	Element
`data-slot="spinner"`	Root

Customizing

Color comes from currentColor, so text-* classes on the spinner or any parent recolor it. color sets the --tone variable and applies text-(--tone).
Size comes from size-* and the ring thickness from border-* (2px by default, 1.5px at xs, 3px at lg).
The spinner is a plain <span> with no client-side JavaScript, so it can render in server components.

API Reference

Spinner

Prop

Type

Also accepts every prop of <span>, such as aria-hidden.

Button — isPending for buttons that are working.
Skeleton — placeholders that match the incoming layout.
Progress Bar — measurable or long-running progress, including ProgressCircle.