Loading Spinner

Anatomy

import {LoadingSpinner} from '@staffbase/design';

<LoadingSpinner />

Examples

Sizes

With progress

API reference

When to use

• For a wait that lasts a few seconds and whose remaining time is unknown, such as saving a form or submitting a short action.
• Inside the area that is loading, such as a thumbnail, a list row, a dialog body, or the loading state of FileUpload.
• With a progress value when the system reports a real completion percentage, such as a file upload.
• When the loading area is too small or too irregular to show placeholder shapes of the incoming content.

When not to use

• Don’t use a spinner as a placeholder for text, list, or card content that is about to render — use Skeleton instead.
• Don’t use a spinner in a region that stays empty because there is no data or no search result — use Empty instead.
• Don’t use a spinner to report the outcome of a finished process, such as a success or a failure — use Banner instead.
• Don’t use a spinner as a decorative graphic or brand animation — it always represents an active process.

How to use

Structure

• Show one spinner per loading region, centered in the area that is loading.
• Reserve the final height of the loading area so content doesn’t jump when the spinner is replaced.
• Show the spinner only after about 300ms of waiting, so fast responses don’t flash an indicator.
• Replace the spinner with the loaded content, an empty state, or an error message as soon as the process ends.
• Don’t leave a region interactive while a spinner covers it — disable the controls inside it until loading finishes.

Sizes

• size accepts 12, 24, 48, and 64, and defaults to 48.
• Use 12 inline with text and in dense rows, such as a table cell.
• Use 24 inside compact controls, such as a select field, a menu, or an input.
• Use 48 for a self-contained region, such as a card, a dialog body, or a thumbnail.
• Use 64 when the spinner is the only element in a full-page or full-region load.
• Pick the size that fits the surrounding space instead of scaling the spinner with CSS — only the four listed sizes are supported.

Progress

• Leave progress unset for indeterminate waits — the ring then rotates continuously.
• Set progress only when the system reports a real percentage, and keep values between 0 and 100.
• The ring fills clockwise as the value grows.
• Keep the value moving forward — don’t reset or reverse it during a single operation.
• The numeric label renders only at sizes 48 and 64; at 12 and 24 the ring alone communicates progress.
• Don’t fake a percentage — an estimate that stalls near 100% is worse than an indeterminate spinner.

Accessibility

• Always set aria-label and name the process it refers to, such as Uploading video.
• With progress set, the spinner is exposed as a progress bar with the current value, so screen readers announce the label together with the percentage.
• Without progress, the spinner is exposed as a status region that is announced when it appears.
• Pair the spinner with visible text when a wait blocks a whole page or region, so the label isn’t available to screen reader users only.
• Don’t rely on the numeric label alone to convey progress — it is hidden from assistive technology and duplicated by the progress value.

Content & UX copy

• Write labels in the present -ing form, such as Loading, Uploading, or Saving.
• Use sentence case and name the object when it adds clarity, such as Uploading video.
• Keep labels to 4 words or fewer.
• Don’t add a trailing ellipsis to the label.
• Don’t put the percentage in the label — the component exposes the progress value on its own.
• Reuse the wording users already see for the same action elsewhere in the product.