Skip to content
lib components / Feedback

Spinner

Provides visual feedback to the user that a process is underway when the duration is uncertain.

Spinner vs. Progress BarExamplesPropertiesGuidelines
import { Spinner } from "@siteimprove/fancylib";

#Spinner vs. Progress Bar

To clarify the differences between Spinner and ProgressBar, a short description is provided.

Component namePurposeUser interactionUsage
SpinnerIndicates an ongoing process with an unknown or indefinite duration.No user interaction is typically possible during the process.Loading content, refreshing data, background tasks.
Progress BarShows the progress of a process with a known or estimated duration.User interaction may be possible during the process (e.g., cancellation).Uploading/downloading files, multi-step forms, progress towards goals.

#Examples

The Spinner component offers several properties to customize its appearance and behavior. The following sections illustrate these properties and explain their appropriate use cases.

#Default

Choose between dark or light variants to ensure contrast with the background.

<div style={{ padding: 16 }}> <Spinner variant="dark" /> </div> <div style={{ padding: 16, background: ColorGrayDarkest }}> <Spinner variant="light" /> </div>

#Size

Select small, medium (default), or large to fit theSpinner appropriately within its container.

<div style={{ display: "flex" }}> <Spinner variant="dark" size="large" /> <Spinner variant="dark" size="medium" /> <Spinner variant="dark" size="small" /> </div>

#Presentational

Set the presentational property to true to hide the Spinnerfrom assistive technologies like screen readers. Use this property when another UI element is already conveying the loading state to assistive technology users.

<Spinner variant="dark" presentational />

#Delayed Appearance

In some cases, the action indicated by the Spinner might complete rapidly. This can lead to the Spinner appearing and disappearing quickly, causing UI flickering. To avoid this, set the appearanceDelay property to control the time (in milliseconds) the Spinner waits before becoming visible. The default delay is 200ms.

const [isVisible, setVisibility] = useState<boolean>(false); return ( <div style={{ display: "flex" }}> <Button onClick={() => setVisibility(!isVisible)} variant="primary"> {isVisible ? "Hide Spinner" : "Show Spinner"} </Button> {isVisible && <Spinner appearanceDelay={1000} variant="dark" />} </div> );

#Properties

PropertyDescriptionDefinedValue
variantRequired
"dark" | "light"Color of the spinner
sizeOptional
"large" | "medium" | "small"Size of the spinner (defaults to `"medium"`)
presentationalOptional
booleanHides the spinner from assistive technology
appearanceDelayOptional
numberTime in milliseconds for delaying appearance (defaults to 200ms )
data-observe-keyOptional
stringUnique string, used by external script e.g. for event tracking
classNameOptional
stringCustom className that's applied to the outermost element (only intended for special cases)
styleOptional
objectStyle object to apply custom inline styles (only intended for special cases)

#Guidelines

#Best practices

#General

Use Spinner when

  • The system is actively loading content or performing an action.
  • The duration of the action is unknown or unpredictable.

#Placement

Spinner is typically used in the following places:

#Style

  • Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of your Spinner to existing components for visual consistency.
  • Set the size property to small when the Spinner's default medium size is too big for its container. Set the property to large when the default size is too small.

#Do not use when

  • Actions with a known or estimated duration (use a Progress Bar).
  • Overuse can be visually distracting.

#Accessibility

#For designers

  • Ensure sufficient color contrast between the Spinner and its background, adhering to WCAG guidelines.

#For developers

  • Set the presentational property to true, when the Spinner's loading message is already communicated to assistive technology users by a different UI element.
  • Place the Spinner inside the container where the loading content will appear.
  • The container in which content will appear, should have aria-busy="true" while loading and aria-busy="false" when done loading.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

  • Use short, clear loading messages (e.g., "Loading...", "Working...").
  • For extended loading times, provide more context (e.g., "Loading results...", "Fetching data...").