Spinner

Show active processes. Simple, clear feedback. Prevent duplicate actions.

Loading invoices

Pulling the last 12 months from Stripe.

1import { Spinner } from '@/components/ui/spinner';
2
3export function Default() {
4  return (
5    <div className="border-border bg-card flex w-full max-w-sm flex-col items-center gap-3 rounded-xl border px-6 py-10">
6      <Spinner />
7      <div className="text-center">
8        <p className="text-sm font-medium">Loading invoices</p>
9        <p className="text-muted-foreground text-xs">Pulling the last 12 months from Stripe.</p>
10      </div>
11    </div>
12  );
13}

Installation

Copy and paste the following code into your project.

1import { cva, type VariantProps } from 'class-variance-authority';
2import * as React from 'react';
3import { cn } from '../lib/cn';
4
5type IconProps = React.SVGProps<SVGSVGElement> & {
6  size?: number | string;
7};
8
9function LoaderIcon({ size = 24, strokeWidth = 1.5, ...props }: IconProps) {
10  return (
11    <svg
12      xmlns="http://www.w3.org/2000/svg"
13      width={size}
14      height={size}
15      viewBox="0 0 24 24"
16      fill="none"
17      stroke="currentColor"
18      strokeWidth={strokeWidth}
19      strokeLinecap="round"
20      strokeLinejoin="round"
21      aria-hidden="true"
22      {...props}
23    >
24      <path d="M21.5 12A9.5 9.5 0 1 1 12 2.5" />
25    </svg>
26  );
27}
28
29const spinnerVariants = cva(
30  'animate-spin motion-reduce:[animation-duration:2.5s] inline-flex items-center justify-center',
31  {
32    variants: {
33      size: {
34        sm: 'w-4 h-4',
35        md: 'w-6 h-6',
36        lg: 'w-8 h-8',
37        xl: 'w-12 h-12',
38      },
39      variant: {
40        default: 'text-foreground',
41        muted: 'text-muted-foreground',
42        success: 'text-success-text',
43        destructive: 'text-destructive-text',
44        warning: 'text-warning-text',
45        info: 'text-info-text',
46      },
47    },
48    defaultVariants: {
49      size: 'md',
50      variant: 'default',
51    },
52  },
53);
54
55export interface SpinnerProps
56  extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof spinnerVariants> {
57  label?: string;
58}
59
60function Spinner({
61  className,
62  size,
63  variant,
64  label = 'Loading',
65  ref,
66  ...props
67}: SpinnerProps & { ref?: React.Ref<HTMLDivElement> }) {
68  return (
69    <div
70      ref={ref}
71      role="status"
72      aria-label={label}
73      aria-live="polite"
74      className={cn(spinnerVariants({ size, variant }), className)}
75      {...props}
76    >
77      <LoaderIcon className="h-full w-full" />
78      <span className="sr-only">{label}</span>
79    </div>
80  );
81}
82Spinner.displayName = 'Spinner';
83
84export { Spinner, spinnerVariants };

Update the import paths to match your project structure.

Anatomy

1import { Spinner } from '@/components/ui/spinner';

1<Spinner />

Examples

Default

Loading invoices

Pulling the last 12 months from Stripe.

1import { Spinner } from '@/components/ui/spinner';
2
3export function Default() {
4  return (
5    <div className="border-border bg-card flex w-full max-w-sm flex-col items-center gap-3 rounded-xl border px-6 py-10">
6      <Spinner />
7      <div className="text-center">
8        <p className="text-sm font-medium">Loading invoices</p>
9        <p className="text-muted-foreground text-xs">Pulling the last 12 months from Stripe.</p>
10      </div>
11    </div>
12  );
13}

Sizes

You can change the size of the spinner using the size prop.

Table cell

Card body

Side panel

Full page

1import { Spinner } from '@/components/ui/spinner';
2
3const sizes = [
4  { size: 'sm' as const, usage: 'Table cell' },
5  { size: 'md' as const, usage: 'Card body' },
6  { size: 'lg' as const, usage: 'Side panel' },
7  { size: 'xl' as const, usage: 'Full page' },
8];
9
10export function Sizes() {
11  return (
12    <div className="grid w-full max-w-md grid-cols-4 gap-3">
13      {sizes.map((entry) => (
14        <div
15          key={entry.size}
16          className="border-border bg-card flex h-28 flex-col items-center justify-center gap-3 rounded-lg border p-3"
17        >
18          <Spinner size={entry.size} />
19          <p className="text-muted-foreground text-center text-xs">{entry.usage}</p>
20        </div>
21      ))}
22    </div>
23  );
24}

Variants

You can change the color of the spinner using the variant prop.

Building web-app

step 3 of 5

Queued: docs site

waiting for a runner

Promoting to production

almost done

Syncing environment variables

18 of 24

Retrying image upload

attempt 2 of 3

Rolling back api-gateway

triggered by CI

1import { Spinner } from '@/components/ui/spinner';
2
3const jobs = [
4  { variant: 'default' as const, label: 'Building web-app', detail: 'step 3 of 5' },
5  { variant: 'muted' as const, label: 'Queued: docs site', detail: 'waiting for a runner' },
6  { variant: 'success' as const, label: 'Promoting to production', detail: 'almost done' },
7  { variant: 'info' as const, label: 'Syncing environment variables', detail: '18 of 24' },
8  { variant: 'warning' as const, label: 'Retrying image upload', detail: 'attempt 2 of 3' },
9  { variant: 'destructive' as const, label: 'Rolling back api-gateway', detail: 'triggered by CI' },
10];
11
12export function Variants() {
13  return (
14    <div className="border-border bg-card divide-border w-full max-w-md divide-y rounded-xl border">
15      {jobs.map((job) => (
16        <div key={job.variant} className="flex items-center gap-3 px-4 py-3">
17          <Spinner size="sm" variant={job.variant} />
18          <p className="min-w-0 flex-1 truncate text-sm">{job.label}</p>
19          <p className="text-muted-foreground shrink-0 text-xs">{job.detail}</p>
20        </div>
21      ))}
22    </div>
23  );
24}

API Reference

Spinner

Prop	Type	Default	Description
`size`	`'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	The size of the spinner
`variant`	`'default' \| 'primary' \| 'muted' \| 'success' \| 'destructive' \| 'warning' \| 'info'`	`'default'`	Visual style
`label`	`string`	`'Loading'`	Accessible name announced by screen readers
`className`	`string`	-	Additional CSS classes

Found something to improve?

Notice a bug, typo, or missing detail on this page? Help us make the documentation better by opening a GitHub issue.

Create an Issue

PreviousSkeleton

NextSprite

1import { Spinner } from '@/components/ui/spinner';

3export function Default() {

4 return (

5 <div className="border-border bg-card flex w-full max-w-sm flex-col items-center gap-3 rounded-xl border px-6 py-10">

6 <Spinner />

7 <div className="text-center">

8 <p className="text-sm font-medium">Loading invoices</p>

9 <p className="text-muted-foreground text-xs">Pulling the last 12 months from Stripe.</p>

10 </div>

11 </div>

12 );

13}

Installation

Copy and paste the following code into your project.

1import { cva, type VariantProps } from 'class-variance-authority';
2import * as React from 'react';
3import { cn } from '../lib/cn';
4
5type IconProps = React.SVGProps<SVGSVGElement> & {
6  size?: number | string;
7};
8
9function LoaderIcon({ size = 24, strokeWidth = 1.5, ...props }: IconProps) {
10  return (
11    <svg
12      xmlns="http://www.w3.org/2000/svg"
13      width={size}
14      height={size}
15      viewBox="0 0 24 24"
16      fill="none"
17      stroke="currentColor"
18      strokeWidth={strokeWidth}
19      strokeLinecap="round"
20      strokeLinejoin="round"
21      aria-hidden="true"
22      {...props}
23    >
24      <path d="M21.5 12A9.5 9.5 0 1 1 12 2.5" />
25    </svg>
26  );
27}
28
29const spinnerVariants = cva(
30  'animate-spin motion-reduce:[animation-duration:2.5s] inline-flex items-center justify-center',
31  {
32    variants: {
33      size: {
34        sm: 'w-4 h-4',
35        md: 'w-6 h-6',
36        lg: 'w-8 h-8',
37        xl: 'w-12 h-12',
38      },
39      variant: {
40        default: 'text-foreground',
41        muted: 'text-muted-foreground',
42        success: 'text-success-text',
43        destructive: 'text-destructive-text',
44        warning: 'text-warning-text',
45        info: 'text-info-text',
46      },
47    },
48    defaultVariants: {
49      size: 'md',
50      variant: 'default',
51    },
52  },
53);
54
55export interface SpinnerProps
56  extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof spinnerVariants> {
57  label?: string;
58}
59
60function Spinner({
61  className,
62  size,
63  variant,
64  label = 'Loading',
65  ref,
66  ...props
67}: SpinnerProps & { ref?: React.Ref<HTMLDivElement> }) {
68  return (
69    <div
70      ref={ref}
71      role="status"
72      aria-label={label}
73      aria-live="polite"
74      className={cn(spinnerVariants({ size, variant }), className)}
75      {...props}
76    >
77      <LoaderIcon className="h-full w-full" />
78      <span className="sr-only">{label}</span>
79    </div>
80  );
81}
82Spinner.displayName = 'Spinner';
83
84export { Spinner, spinnerVariants };

Update the import paths to match your project structure.

Examples

Default

Loading invoices

Pulling the last 12 months from Stripe.

1import { Spinner } from '@/components/ui/spinner';
2
3export function Default() {
4  return (
5    <div className="border-border bg-card flex w-full max-w-sm flex-col items-center gap-3 rounded-xl border px-6 py-10">
6      <Spinner />
7      <div className="text-center">
8        <p className="text-sm font-medium">Loading invoices</p>
9        <p className="text-muted-foreground text-xs">Pulling the last 12 months from Stripe.</p>
10      </div>
11    </div>
12  );
13}

Sizes

You can change the size of the spinner using the size prop.

Table cell

Card body

Side panel

Full page

1import { Spinner } from '@/components/ui/spinner';
2
3const sizes = [
4  { size: 'sm' as const, usage: 'Table cell' },
5  { size: 'md' as const, usage: 'Card body' },
6  { size: 'lg' as const, usage: 'Side panel' },
7  { size: 'xl' as const, usage: 'Full page' },
8];
9
10export function Sizes() {
11  return (
12    <div className="grid w-full max-w-md grid-cols-4 gap-3">
13      {sizes.map((entry) => (
14        <div
15          key={entry.size}
16          className="border-border bg-card flex h-28 flex-col items-center justify-center gap-3 rounded-lg border p-3"
17        >
18          <Spinner size={entry.size} />
19          <p className="text-muted-foreground text-center text-xs">{entry.usage}</p>
20        </div>
21      ))}
22    </div>
23  );
24}

Variants

You can change the color of the spinner using the variant prop.

Building web-app

step 3 of 5

Queued: docs site

waiting for a runner

Promoting to production

almost done

Syncing environment variables

18 of 24

Retrying image upload

attempt 2 of 3

Rolling back api-gateway

triggered by CI

1import { Spinner } from '@/components/ui/spinner';
2
3const jobs = [
4  { variant: 'default' as const, label: 'Building web-app', detail: 'step 3 of 5' },
5  { variant: 'muted' as const, label: 'Queued: docs site', detail: 'waiting for a runner' },
6  { variant: 'success' as const, label: 'Promoting to production', detail: 'almost done' },
7  { variant: 'info' as const, label: 'Syncing environment variables', detail: '18 of 24' },
8  { variant: 'warning' as const, label: 'Retrying image upload', detail: 'attempt 2 of 3' },
9  { variant: 'destructive' as const, label: 'Rolling back api-gateway', detail: 'triggered by CI' },
10];
11
12export function Variants() {
13  return (
14    <div className="border-border bg-card divide-border w-full max-w-md divide-y rounded-xl border">
15      {jobs.map((job) => (
16        <div key={job.variant} className="flex items-center gap-3 px-4 py-3">
17          <Spinner size="sm" variant={job.variant} />
18          <p className="min-w-0 flex-1 truncate text-sm">{job.label}</p>
19          <p className="text-muted-foreground shrink-0 text-xs">{job.detail}</p>
20        </div>
21      ))}
22    </div>
23  );
24}

Prop

Type

Default

Description

size

'sm' | 'md' | 'lg' | 'xl'

'md'

The size of the spinner

variant

'default'

Visual style

label

string

'Loading'

Accessible name announced by screen readers

className

string

Additional CSS classes