Skip to content
Shaken UI
Sign in

Spinner

Save

A 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
Dots
Loading, xsLoading, smLoading, mdLoading, lg
acme/webSyncing 24 files
acme/apiIndexing

Installation

npx @shakenui/cli add spinner

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add spinner --dry-run

Usage

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

PropTypeDefaultDescription
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.
labelReactNode"Loading"What is loading. Read by screen readers, and shown beside the spinner with showLabel.
showLabelbooleanfalseShows the label as secondary text beside the spinner.
decorativebooleanfalseHides 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.tsxShow
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>
  );
}