Skip to content

Spinner

Use Spinner for a short wait of unknown length: a panel refreshing, a section loading, content being replaced. When content of a known shape is on the way, a Skeleton keeps the layout steady; when you can tell how far along the work is, use Progress; a Button has its own loading.

Spinner shows that something is loading. On its own it sits inline; wrapped around content it covers that content while loading. The default ring is one growing SVG arc; type="pixel" draws Raft’s four-pixel mark instead and type="dots" three dots.

Demos

Size

Four named sizes, or any size in px. The spinner takes its container’s text color; on a colored fill, set that to the fill’s text-on-fill color and use variant="inverse" for a stronger track.

Type

type="ring" (the default) is one SVG arc. type="pixel" is four square pixels in a 2x2 grid, lit in turn clockwise; it takes the text color like the ring. Its named sizes are 9.5, 12, 14 and 19px across (4, 5, 6 and 8px pixels). A px size is the whole mark: the gap is a sixth of it and each pixel (size - gap) / 2. With reduced motion the pixels stop and the first stays lit.

type="dots" is three round dots in a row; each rises half a dot and brightens in turn, left to right, every 1.2s. Its named sizes are 12, 16, 20 and 32px across (3, 4, 5 and 8px dots, the gap half a dot) and the mark is two dots high, so the rise stays inside it. A px size is the row’s width: each dot a quarter of it, each gap an eighth. With reduced motion the dots stand still. The demo shows all three types in a light and a dark scope.

Thinking and typing

The dots follow a few words to say work is under way without a fixed end: “Thinking”, “Kate is typing”, or alone in a chat bubble. Give aria-label the same words, so a screen reader says “Thinking” rather than the default “Loading”.

Description

Covering content

With children, the spinner sits over them and dims them while show is true; the content is marked aria-busy and can’t be clicked.

Delay

delay waits before showing, so a quick operation never flashes a spinner. Hiding is immediate.

Custom icon

icon replaces the ring and spins it; rotate={false} keeps it still. Both are ignored with type="pixel" and type="dots".

Props

NameTypeDefaultDescriptionVersion
typering | pixel | dotsringring is the theme’s ring; pixel is the four-pixel mark and dots three dots, the same in every theme.Unreleased
sizexs | sm | md | lg | numbersmA named size or px; with type="pixel" or type="dots" a px size is the mark’s total width.Unreleased
variantdefault | inversedefaultinverse strengthens the track for colored backgrounds; the color itself comes from the container’s text color.Unreleased
descriptionReactNodeundefinedText under the spinner.Unreleased
childrenReactNodeundefinedContent to cover while loading.Unreleased
showbooleantrueShows the spinner; with children, false also un-dims them.Unreleased
delaynumberundefinedMilliseconds to wait before showing.Unreleased
iconReactNodeundefinedReplaces the ring; only for type="ring".Unreleased
rotatebooleantrueSpins a custom icon; only for type="ring".Unreleased
contentClassNamestringundefinedClass for the covered content.Unreleased
contentStyleCSSPropertiesundefinedStyle for the covered content.Unreleased

The spinner is a role="status" element named from the locale (“Loading” / “加载中”); pass aria-label to say what is loading. Without children the root is an inline span, with children a block div; ref and other attributes go to that root.