Skip to content
Components, switch product

Spinner

<gui-spinner> shows a wait of unknown length, such as results loading. It is the glyph the button and the file uploads spin while they are busy, as an element of its own. It takes the color and the size of the text it sits in.

Code of the example above
SpinnerBasic.tsx
import { GuiSpinner } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';
export function SpinnerBasic() {
return <GuiSpinner label="Loading results" />;
}

The element’s entry point is @golemui/gui-components/spinner, which registers <gui-spinner> and nothing else. To install the package and load the stylesheet, see Installation.

The @golemui/gui-components/react components have typed props and an on* prop for each event. React 18 or later.

SpinnerExample.tsx
import { GuiSpinner } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';
export function SpinnerExample() {
return (
<GuiSpinner
label="Loading results"
/>
);
}

The label says what the wait is for. Screen readers read it; the page doesn’t show it. For a task that reports how far it has got, use a progress bar instead.

Properties

Property Type Default Description
label string – What the wait is for, read out by screen readers. Without one the spinner is decorative.

The glyph is 1.25em: it grows with the font size of the text around it. --gui-spinner-color sets a color other than the text’s, as on the last line below.

Body text

Larger text

Extra large text

Code of the example above
SpinnerSizes.tsx
import type { CSSProperties } from 'react';
import { GuiSpinner } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';
const primary = {
'--gui-spinner-color': 'var(--gui-intent-primary)',
} as CSSProperties;
export function SpinnerSizes() {
return (
<>
<p>
<GuiSpinner label="Loading" /> Body text
</p>
<p style={{ fontSize: '1.5rem' }}>
<GuiSpinner label="Loading" /> Larger text
</p>
<p style={{ fontSize: '2rem' }}>
<GuiSpinner label="Loading" style={primary} /> Extra large text
</p>
</>
);
}

A spinner with no text around it, such as one that fills a panel while its content loads, takes a size of its own from --gui-spinner-size. Its label is then the only thing that says what is loading.

Code of the example above
SpinnerStandalone.tsx
import type { CSSProperties } from 'react';
import { GuiSpinner } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';
const large = {
'--gui-spinner-size': '2.5rem',
'--gui-spinner-color': 'var(--gui-intent-primary)',
} as CSSProperties;
export function SpinnerStandalone() {
return <GuiSpinner label="Loading the report" style={large} />;
}

When the text next to the spinner already says what is happening, leave the label out: the spinner is then decorative, and screen readers read only the text.

Saving your changes…

Code of the example above
SpinnerDecorative.tsx
import { GuiSpinner } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';
export function SpinnerDecorative() {
return (
<p>
<GuiSpinner /> Saving your changes…
</p>
);
}

Screen readers announce the label when it changes. Most of them announce nothing when the spinner is added to the page with its label already set, so keep the spinner in the page, hidden, and set its label when the wait starts. Mark what is loading with aria-busy while it loads, and clear the label when it ends.

Code of the example above
SpinnerAnnounce.tsx
import { useState } from 'react';
import { GuiButton, GuiSpinner } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';
export function SpinnerAnnounce() {
const [loading, setLoading] = useState(false);
const [results, setResults] = useState('');
const load = () => {
setLoading(true);
setResults('');
// Stands in for a request to your server.
setTimeout(() => {
setLoading(false);
setResults('12 results');
}, 2000);
};
return (
<>
<p>
<GuiButton label="Load results" onClick={load} />{' '}
<GuiSpinner
hidden={!loading}
label={loading ? 'Loading results' : undefined}
/>
</p>
<div aria-busy={loading}>
<output>{results}</output>
</div>
</>
);
}

<gui-spinner> renders into the light DOM. These are its parts and their public classes:

gui-spinner
<gui-spinner label="Loading results">
<span class="gui-spinner__icon">
<svg
xmlns="http://www.w3.org/2000/svg"
width="16"
height="16"
viewBox="0 0 256 256"
fill="currentColor"
class="gui-spinner__glyph"
aria-hidden="true"
>
<path d="…"></path>
</svg>
</span>
<span class="gui-spinner__status gui-visually-hidden" role="status">
Loading results
</span>
</gui-spinner>
ClassPart
gui-spinner__iconThe box around the glyph.
gui-spinner__glyphThe glyph, an <svg> that turns. Screen readers skip it.
gui-spinner__statusThe status region with the label, hidden on screen by gui-visually-hidden.

The spinner is an inline flex box, display: inline-flex, and still hides with the hidden attribute.

TokenWhat it styles
--gui-spinner-sizeThe width and height of the glyph. 1.25em by default.
--gui-spinner-colorThe color of the glyph. currentColor by default.
styles.css
/* Bigger spinners in the dashboard cards, in the primary color. */
.dashboard-card {
--gui-spinner-size: 2rem;
--gui-spinner-color: var(--gui-intent-primary);
}

To restyle beyond the tokens, see Overriding styles; for dark mode and the Clay theme, see Themes and dark mode.

  • Label. The label goes in a role="status" region inside the spinner, hidden on screen. Screen readers announce it when it changes, after what they are reading. Without a label, the spinner says nothing.
  • Glyph. The glyph is decorative, aria-hidden="true".
  • Busy. Set aria-busy="true" on what is loading, such as the results list, and remove it when the content is there. Keep the spinner outside that element: screen readers can hold back what changes inside a busy element, the spinner’s label too.
  • Motion. With reduced motion, the glyph turns three times slower.
  • Color. The glyph takes the text color, so it keeps the text’s contrast with the page.

The spinner takes no focus and has no keys of its own.

What every element shares is in Accessibility.