Spinner

How to build a spinner that shows something is busy, without getting in the way of screen readers, reduced motion or the layout around it.

Spinners tell people that something is busy, whether that's saving a form, loading search results or checking for updates, when there's no telling how long it'll take. They're one of the simplest components in any interface, and still easy to get wrong. Think of a spinner that screen readers read out as "image", one that keeps turning for people who asked for less motion, or one that pushes the page down as it appears.

This page walks you through building one the right way. We'll look at:

User Interface (UI)

How a spinner looks, from its parts, size and colour to how it moves and the one variable you can set.

User Experience (UX)

How a spinner behaves for every person and setting, so it's accessible, predictable, clear in every state and adaptive.

Developer Experience (DX)

How developers use the Spinner, with no props, events or slots, and one implementation that every component shares.

Agentic Experience (AX)

How agents read, build and check a spinner, from the text around it to its contract, its DOM and its tests.

At a glance

Every example on this page runs on our reference implementation, which does its part of every rule in the checklist, and is the same one the Button shows while it's loading. The code under each example comes in React, Vue, Svelte, Angular, Solid, Astro and Vanilla, written for a Spinner with the same API in each. Pick yours from the Framework select above the sidebar. Vanilla is plain HTML and JavaScript, so it writes out the markup from the DOM contract.

AspectSpinner
Element<svg>
RoleNone, since it's hidden from assistive technologies with aria-hidden
NameNone. Whatever shows it says what's loading, like the Button with its loadingLabel
KeyboardNone, since it can't be focused
StatesNone of its own. It turns while it's in the page, and pulses when someone prefers reduced motion
Size1em, the size of the text around it, unless --spinner--size sets another
ColourcurrentColor, the colour of the text around it
Used byButton
WCAG 2.21.1.1, 1.4.4, 1.4.11, 2.2.2, 2.3.3 and 4.1.3

Checklist

Here's every rule in one place, along with where it comes from and how to check it. A spinner meets the standard when it meets every must, and each should is expected unless you have a good reason not to follow it.

The scope says who meets a rule. Component rules are met by the Spinner itself, so they're the ones to check when you build or review one. Usage rules are met by the screens and components that show it, like saying what's loading, so they're the ones to check when you review a screen. Both rules need the two to work together, like contrast: the Spinner takes the colour of the text around it, as long as that text passes.

The basis says where a rule comes from. A few rules rest on WCAG 2.2, which we follow at level AA, and name the success criteria behind them. The rest are Open Components rules, which are our own, like showing one spinner per wait. Where a rule goes further than WCAG asks at level AA, its basis says so: the reduced-motion rule comes from level AAA, and a rule that asks for more than its criterion says beyond, like announcing how a wait went, which WCAG only asks for when there's a message to announce.

You'll find the rules for each layer on its page:

Reference implementation

Our Vue 3 reference implementation does its part of every rule on this page, powers every example on it and is what the Button shows while it's loading. Feel free to copy it into your design system and change how it looks, but try to keep how it behaves: hidden from assistive technologies, drawn in currentColor, 1em by default and pulsing with reduced motion.

The tests are in Spinner.test.ts. To run them, you'll need Vitest, set to environment: "jsdom" and globals: true, along with @testing-library/vue and @testing-library/jest-dom.

<template>
  <svg class="spinner" viewBox="0 0 16 16" aria-hidden="true">
    <!-- Visual only: whatever shows the spinner tells screen readers what's loading. -->
    <circle data-slot="track" cx="8" cy="8" r="6.5" fill="none" stroke="currentColor" stroke-width="2" opacity="0.25" />
    <path
      data-slot="indicator"
      d="M8 1.5a6.5 6.5 0 0 1 6.5 6.5"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
    />
  </svg>
</template>

<style scoped>
/* The same layer order as Tailwind CSS. The spinner's styles go in `components`,
   so a class of yours that sets its size wins without any specificity tricks. */
@layer theme, base, components, utilities;

@layer components {
  .spinner {
    /* The size of the text around it, like an icon. Components that place it set their own. */
    --spinner--size: 1em;

    /* Inline, like a letter, even under resets that make every svg a block, like Tailwind's Preflight. */
    display: inline-block;
    flex-shrink: 0;
    width: var(--spinner--size);
    height: var(--spinner--size);
    /* Centred on the text around it, when it sits in a line of text. */
    vertical-align: -0.125em;
    animation: spinner-turn 0.8s linear infinite;
  }
  @keyframes spinner-turn {
    to {
      rotate: 1turn;
    }
  }
  @keyframes spinner-pulse {
    50% {
      opacity: 0.4;
    }
  }

  /* With reduced motion, the spinner pulses instead of turning. */
  @media (prefers-reduced-motion: reduce) {
    .spinner {
      animation: spinner-pulse 1.6s ease-in-out infinite;
    }
  }
}
</style>

Sources

Copyright © 2026