Loading States

Match the loading indicator to the wait — when to show nothing, a spinner, a progress bar, or a skeleton, and how to keep any of them from flashing.

Dependencies

Spinner

Progress

Skeleton

Avatar

useDelayedLoading

Overview

Foundations ships every piece of a loading state — Spinner (indeterminate), Progress (determinate), Skeleton (content-shaped placeholder), and useDelayedLoading (anti-flash timing). The hard part isn’t any one of them; it’s knowing which to reach for, and when. This guide is the decision.

The wait-time ladder

How long the user will wait determines what you show. The thresholds come from Primer’s loading guidance:

Expected wait	Indicator
< 1s	Nothing — an indicator would only flash
1–3s	Spinner — indeterminate, “something’s happening”
3–10s	Progress — determinate, “this much is done”
10s+	Progress, and let the user keep working

The instinct to “always show a spinner so the user knows something happened” backfires below a second: a spinner that appears and vanishes within a couple of frames reads as a glitch and makes the product feel slower, not faster.

Two decisions

Showing the right loading state is two separate calls, and you make both:

Which indicator fits the expected wait — the ladder above.
When it’s allowed on screen — wrap its visibility in useDelayedLoading so it’s deferred past a short delay and, once shown, held for a minimum. That’s what guarantees a spinner or a progress bar never flashes, no matter how fast the work resolves on a good connection.

Choosing an indicator by duration

Each button simulates work of a different length. The demo picks the indicator the ladder prescribes and gates its visibility with useDelayedLoading. Note that the quick task shows nothing at all.

Idle

Quick: Under 1s → show nothing. An indicator would only flash.
Medium: 1–3s → an indeterminate spinner.
Long: 3–10s → a determinate progress bar.

import { useRef, useState } from 'react';

import { useDelayedLoading } from '@/foundations/hooks/use-delayed-loading';
import { useTicker } from '@/foundations/hooks/use-ticker';
import { Button } from '@/components/button';
import { Progress } from '@/components/progress';
import { Spinner } from '@/components/spinner';
import type { PreviewMeta } from '@/lib/preview';

type Indicator = 'none' | 'spinner' | 'progress';

// The wait-time ladder: pick an indicator from the expected duration.
const indicatorFor = (expectedMs: number): Indicator =>
  expectedMs < 1000 ? 'none' : expectedMs < 3000 ? 'spinner' : 'progress';

const cases = [
  {
    label: 'Quick',
    duration: 200,
    caption: 'Under 1s → show nothing. An indicator would only flash.',
  },
  {
    label: 'Medium',
    duration: 2000,
    caption: '1–3s → an indeterminate spinner.',
  },
  {
    label: 'Long',
    duration: 6000,
    caption: '3–10s → a determinate progress bar.',
  },
];

function LoadingStatesLadderPreview() {
  const [isLoading, setIsLoading] = useState(false);
  const [indicator, setIndicator] = useState<Indicator>('none');
  const [value, setValue] = useState(0);

  const showLoading = useDelayedLoading(isLoading);

  const timeout = useRef<number | null>(null);
  const startedAt = useRef(0);
  const duration = useRef(0);

  const ticker = useTicker(() => {
    const pct = Math.min(
      100,
      ((performance.now() - startedAt.current) / duration.current) * 100
    );
    setValue(pct);
    if (pct >= 100) return false;
  });

  const load = (ms: number) => {
    if (timeout.current) window.clearTimeout(timeout.current);

    const next = indicatorFor(ms);
    setIndicator(next);
    setValue(0);
    setIsLoading(true);

    if (next === 'progress') {
      startedAt.current = performance.now();
      duration.current = ms;
      ticker.start();
    }

    timeout.current = window.setTimeout(() => {
      setIsLoading(false);
      ticker.stop();
    }, ms);
  };

  return (
    <div className="flex flex-col items-center gap-6">
      <div className="flex flex-wrap justify-center gap-2">
        {cases.map((c) => (
          <Button
            key={c.label}
            variant="outline"
            disabled={isLoading}
            onClick={() => load(c.duration)}
          >
            {c.label} (
            {c.duration < 1000 ? `${c.duration}ms` : `${c.duration / 1000}s`})
          </Button>
        ))}
      </div>

      <div className="flex h-8 w-64 items-center justify-center text-foreground-secondary text-sm">
        {showLoading && indicator === 'spinner' && (
          <span className="flex items-center gap-2">
            <Spinner /> Loading…
          </span>
        )}
        {showLoading && indicator === 'progress' && (
          <Progress value={value} className="w-full" />
        )}
        {!(showLoading && indicator !== 'none') && (
          <span className="opacity-60">{isLoading ? 'Working…' : 'Idle'}</span>
        )}
      </div>

      <ul className="max-w-sm space-y-1 text-center text-foreground-secondary text-xs">
        {cases.map((c) => (
          <li key={c.label}>
            <strong className="text-foreground">{c.label}</strong>: {c.caption}
          </li>
        ))}
      </ul>
    </div>
  );
}

export const meta = {
  layout: 'centered',
} satisfies PreviewMeta;

export default LoadingStatesLadderPreview;

Loading known content

Duration isn’t the only axis. When you already know the shape of what’s loading — a card, a row, a profile — render a Skeleton in that shape instead of a spinner. It preserves layout so nothing jumps when the real content arrives, and it communicates what is coming, not just that something is. Gate it with useDelayedLoading too, so a fast response doesn’t flash a skeleton.

Ada LovelaceAnalytical Engine

The skeleton mirrors the card's layout, so nothing shifts when content arrives. A quick reload finishes before the delay, so the skeleton never flashes.

import { useRef, useState } from 'react';

import { useDelayedLoading } from '@/foundations/hooks/use-delayed-loading';
import { Avatar } from '@/components/avatar';
import { Button } from '@/components/button';
import { Skeleton } from '@/components/skeleton';
import type { PreviewMeta } from '@/lib/preview';

function LoadingStatesSkeletonPreview() {
  const [isLoading, setIsLoading] = useState(false);
  const timeout = useRef<number | null>(null);

  const showSkeleton = useDelayedLoading(isLoading);

  const reload = (ms: number) => {
    if (timeout.current) window.clearTimeout(timeout.current);
    setIsLoading(true);
    timeout.current = window.setTimeout(() => setIsLoading(false), ms);
  };

  return (
    <div className="flex flex-col items-center gap-6">
      <div className="flex gap-2">
        <Button
          variant="outline"
          disabled={isLoading}
          onClick={() => reload(1500)}
        >
          Reload (1.5s)
        </Button>
        <Button
          variant="outline"
          disabled={isLoading}
          onClick={() => reload(150)}
        >
          Quick reload (150ms)
        </Button>
      </div>

      <div className="w-64 rounded-xl border border-border p-4">
        {showSkeleton ? (
          <div className="flex items-center gap-3">
            <Skeleton className="size-12 rounded-full" />
            <div className="flex flex-1 flex-col gap-2">
              <Skeleton className="h-3 w-2/3" />
              <Skeleton className="h-3 w-1/2" />
            </div>
          </div>
        ) : (
          <div className="flex items-center gap-3">
            <Avatar size="lg">
              <Avatar.Fallback>Ada Lovelace</Avatar.Fallback>
            </Avatar>
            <div className="flex flex-1 flex-col">
              <span className="font-medium text-sm">Ada Lovelace</span>
              <span className="text-foreground-secondary text-xs">
                Analytical Engine
              </span>
            </div>
          </div>
        )}
      </div>

      <p className="max-w-sm text-center text-foreground-secondary text-xs">
        The skeleton mirrors the card's layout, so nothing shifts when content
        arrives. A quick reload finishes before the delay, so the skeleton never
        flashes.
      </p>
    </div>
  );
}

export const meta = {
  layout: 'centered',
} satisfies PreviewMeta;

export default LoadingStatesSkeletonPreview;

10 seconds and beyond

Past ten seconds, a blocking indicator is hostile. Keep a determinate Progress so the wait stays legible, but stop blocking the UI: let the user move elsewhere while the work runs, and surface completion out-of-band (a toast, a badge, an updated row) rather than holding them on a frozen screen.

A note on motion

Spinner, Progress, and Skeleton animate regardless of prefers-reduced-motion — a loading indicator communicates state, so freezing it would break the signal. See the Spinner page for the rationale.

Hierarchical Selection

Performance tracking & bundle analyzer