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.
import { GuiSpinner } from '@golemui/gui-components/react';import '@golemui/gui-components/index.css';
export function SpinnerBasic() { return <GuiSpinner label="Loading results" />;}import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';import '@golemui/gui-components/spinner';
@Component({ selector: 'app-spinner-basic', schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` <gui-spinner label="Loading results"></gui-spinner> `,})export class SpinnerBasicComponent {}<script setup lang="ts">import '@golemui/gui-components/spinner';import '@golemui/gui-components/index.css';</script>
<template> <gui-spinner label="Loading results"></gui-spinner></template>import { LitElement, html } from 'lit';import { customElement } from 'lit/decorators.js';import '@golemui/gui-components/spinner';import '@golemui/gui-components/index.css';
@customElement('spinner-basic')export class SpinnerBasic extends LitElement { protected override createRenderRoot() { return this; }
override render() { return html`<gui-spinner label="Loading results"></gui-spinner>`; }}<gui-spinner label="Loading results"></gui-spinner>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.
import { GuiSpinner } from '@golemui/gui-components/react';import '@golemui/gui-components/index.css';
export function SpinnerExample() { return ( <GuiSpinner label="Loading results" /> );}Add CUSTOM_ELEMENTS_SCHEMA to the component that uses the tags, and the stylesheet to styles in angular.json.
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';import '@golemui/gui-components/spinner';
@Component({ selector: 'app-spinner-example', schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` <gui-spinner label="Loading results" ></gui-spinner> `,})export class SpinnerExampleComponent {}"styles": ["node_modules/@golemui/gui-components/lib/styles/index.css"]Tell Vue's compiler that gui-* tags are custom elements, and add the typings once for typed props and @gui-* handlers.
<script setup lang="ts">import '@golemui/gui-components/spinner';import '@golemui/gui-components/index.css';</script>
<template> <gui-spinner label="Loading results" /></template>vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('gui-') } },});import type {} from '@golemui/gui-components/vue';The page's stylesheet styles the gui-* elements, so it only reaches them outside a shadow root. Render the host component into the light DOM too, as below, or load the stylesheet into its shadow root.
import { LitElement, html } from 'lit';import { customElement } from 'lit/decorators.js';import '@golemui/gui-components/spinner';import '@golemui/gui-components/index.css';
@customElement('spinner-example')export class SpinnerExample extends LitElement { protected override createRenderRoot() { return this; }
override render() { return html` <gui-spinner label="Loading results" ></gui-spinner> `; }}With any bundler, such as Vite. Import the element once, anywhere, and use the tag in your markup.
<gui-spinner label="Loading results"></gui-spinner>
<script type="module" src="./main.js"></script>import '@golemui/gui-components/spinner';import '@golemui/gui-components/index.css';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. |
Examples
Section titled “Examples”Sizes and colors
Section titled “Sizes and colors”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.
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> </> );}import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';import '@golemui/gui-components/spinner';
@Component({ selector: 'app-spinner-sizes', schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` <p><gui-spinner label="Loading"></gui-spinner> Body text</p> <p style="font-size: 1.5rem"> <gui-spinner label="Loading"></gui-spinner> Larger text </p> <p style="font-size: 2rem"> <gui-spinner label="Loading" style="--gui-spinner-color: var(--gui-intent-primary)" ></gui-spinner> Extra large text </p> `,})export class SpinnerSizesComponent {}<script setup lang="ts">import '@golemui/gui-components/spinner';import '@golemui/gui-components/index.css';</script>
<template> <p><gui-spinner label="Loading"></gui-spinner> Body text</p> <p style="font-size: 1.5rem"> <gui-spinner label="Loading"></gui-spinner> Larger text </p> <p style="font-size: 2rem"> <gui-spinner label="Loading" style="--gui-spinner-color: var(--gui-intent-primary)" ></gui-spinner> Extra large text </p></template>import { LitElement, html } from 'lit';import { customElement } from 'lit/decorators.js';import '@golemui/gui-components/spinner';import '@golemui/gui-components/index.css';
@customElement('spinner-sizes')export class SpinnerSizes extends LitElement { protected override createRenderRoot() { return this; }
override render() { return html` <p><gui-spinner label="Loading"></gui-spinner> Body text</p> <p style="font-size: 1.5rem"> <gui-spinner label="Loading"></gui-spinner> Larger text </p> <p style="font-size: 2rem"> <gui-spinner label="Loading" style="--gui-spinner-color: var(--gui-intent-primary)" ></gui-spinner> Extra large text </p> `; }}<p><gui-spinner label="Loading"></gui-spinner> Body text</p><p style="font-size: 1.5rem"> <gui-spinner label="Loading"></gui-spinner> Larger text</p><p style="font-size: 2rem"> <gui-spinner label="Loading" style="--gui-spinner-color: var(--gui-intent-primary)" ></gui-spinner> Extra large text</p>On its own
Section titled “On its own”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.
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} />;}import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';import '@golemui/gui-components/spinner';
@Component({ selector: 'app-spinner-standalone', schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` <gui-spinner label="Loading the report" style=" --gui-spinner-size: 2.5rem; --gui-spinner-color: var(--gui-intent-primary); " ></gui-spinner> `,})export class SpinnerStandaloneComponent {}<script setup lang="ts">import '@golemui/gui-components/spinner';import '@golemui/gui-components/index.css';</script>
<template> <gui-spinner label="Loading the report" style=" --gui-spinner-size: 2.5rem; --gui-spinner-color: var(--gui-intent-primary); " ></gui-spinner></template>import { LitElement, html } from 'lit';import { customElement } from 'lit/decorators.js';import '@golemui/gui-components/spinner';import '@golemui/gui-components/index.css';
@customElement('spinner-standalone')export class SpinnerStandalone extends LitElement { protected override createRenderRoot() { return this; }
override render() { return html` <gui-spinner label="Loading the report" style=" --gui-spinner-size: 2.5rem; --gui-spinner-color: var(--gui-intent-primary); " ></gui-spinner> `; }}<gui-spinner label="Loading the report" style=" --gui-spinner-size: 2.5rem; --gui-spinner-color: var(--gui-intent-primary); "></gui-spinner>Next to text that says it
Section titled “Next to text that says it”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.
import { GuiSpinner } from '@golemui/gui-components/react';import '@golemui/gui-components/index.css';
export function SpinnerDecorative() { return ( <p> <GuiSpinner /> Saving your changes… </p> );}import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';import '@golemui/gui-components/spinner';
@Component({ selector: 'app-spinner-decorative', schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` <p><gui-spinner></gui-spinner> Saving your changes…</p> `,})export class SpinnerDecorativeComponent {}<script setup lang="ts">import '@golemui/gui-components/spinner';import '@golemui/gui-components/index.css';</script>
<template> <p><gui-spinner></gui-spinner> Saving your changes…</p></template>import { LitElement, html } from 'lit';import { customElement } from 'lit/decorators.js';import '@golemui/gui-components/spinner';import '@golemui/gui-components/index.css';
@customElement('spinner-decorative')export class SpinnerDecorative extends LitElement { protected override createRenderRoot() { return this; }
override render() { return html`<p><gui-spinner></gui-spinner> Saving your changes…</p>`; }}<p><gui-spinner></gui-spinner> Saving your changes…</p>Announcing a wait
Section titled “Announcing a wait”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.
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> </> );}import { Component, CUSTOM_ELEMENTS_SCHEMA, signal } from '@angular/core';import '@golemui/gui-components/button';import '@golemui/gui-components/spinner';
@Component({ selector: 'app-spinner-announce', schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` <p> <gui-button label="Load results" (click)="load()"></gui-button> <gui-spinner [hidden]="!loading()" [label]="loading() ? 'Loading results' : undefined" ></gui-spinner> </p> <div [attr.aria-busy]="loading()"> <output>{{ results() }}</output> </div> `,})export class SpinnerAnnounceComponent { loading = signal(false); results = signal('');
load() { this.loading.set(true); this.results.set(''); // Stands in for a request to your server. setTimeout(() => { this.loading.set(false); this.results.set('12 results'); }, 2000); }}<script setup lang="ts">import { ref } from 'vue';import '@golemui/gui-components/button';import '@golemui/gui-components/spinner';import '@golemui/gui-components/index.css';
const loading = ref(false);const results = ref('');
function load() { loading.value = true; results.value = ''; // Stands in for a request to your server. setTimeout(() => { loading.value = false; results.value = '12 results'; }, 2000);}</script>
<template> <p> <gui-button label="Load results" @click="load"></gui-button> <gui-spinner :hidden="!loading" :label="loading ? 'Loading results' : undefined" ></gui-spinner> </p> <div :aria-busy="loading"> <output>{{ results }}</output> </div></template>import { LitElement, html } from 'lit';import { customElement, state } from 'lit/decorators.js';import '@golemui/gui-components/button';import '@golemui/gui-components/spinner';import '@golemui/gui-components/index.css';
@customElement('spinner-announce')export class SpinnerAnnounce extends LitElement { @state() private loading = false; @state() private results = '';
protected override createRenderRoot() { return this; }
private load() { this.loading = true; this.results = ''; // Stands in for a request to your server. setTimeout(() => { this.loading = false; this.results = '12 results'; }, 2000); }
override render() { return html` <p> <gui-button label="Load results" @click=${this.load}></gui-button> <gui-spinner ?hidden=${!this.loading} .label=${this.loading ? 'Loading results' : undefined} ></gui-spinner> </p> <div aria-busy=${this.loading ? 'true' : 'false'}> <output>${this.results}</output> </div> `; }}<p> <gui-button id="results-load" label="Load results"></gui-button> <gui-spinner id="results-spinner" hidden></gui-spinner></p><div id="results" aria-busy="false"> <output id="results-output"></output></div>
<script type="module"> const results = document.querySelector('#results'); const spinner = document.querySelector('#results-spinner'); const output = document.querySelector('#results-output');
document.querySelector('#results-load').addEventListener('click', () => { results.setAttribute('aria-busy', 'true'); output.textContent = ''; spinner.hidden = false; spinner.label = 'Loading results'; // Stands in for a request to your server. setTimeout(() => { spinner.hidden = true; spinner.label = undefined; results.setAttribute('aria-busy', 'false'); output.textContent = '12 results'; }, 2000); });</script>Styling
Section titled “Styling”Anatomy
Section titled “Anatomy”<gui-spinner> renders into the light DOM. These are its parts and their public classes:
<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>| Class | Part |
|---|---|
gui-spinner__icon | The box around the glyph. |
gui-spinner__glyph | The glyph, an <svg> that turns. Screen readers skip it. |
gui-spinner__status | The 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.
Tokens
Section titled “Tokens”| Token | What it styles |
|---|---|
--gui-spinner-size | The width and height of the glyph. 1.25em by default. |
--gui-spinner-color | The color of the glyph. currentColor by default. |
/* 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.
Accessibility
Section titled “Accessibility”- Label. The
labelgoes in arole="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.