Skip to main content

Loading

Signals that something is happening when you cannot say how long it will take.

import { Loading } from "@/fragments/ui";Source

Preview

<Loading label="Loading content" />

Installation

npx @usefragments/cli add loading

Writes src/fragments/ui/components/Loading plus what it imports, the globals stylesheet, and .fragments/registry-lock.json, then prints the packages to add. No account, no key.

Your own registry: publish from Fragments Cloud and add --registry org/name. Connect a workspace.

Anatomy

Loading is a compound: import the root and reach its parts through dot notation.

  • Loading.Inline
  • Loading.Screen

Examples

Sizes

sm inside controls, xl for a whole page.

import { Stack } from '@/components/Stack';

<Stack direction="row" gap="lg" align="center">
  <Loading size="sm" label="Loading" />
  <Loading size="md" label="Loading" />
  <Loading size="lg" label="Loading" />

Dots

Three bouncing dots, at home in a message thread.

<Loading kind="dots" label="Sending message" />

Pulse

One breathing dot for ambient background work.

<Loading kind="pulse" label="Syncing" />

Colors

Accent, muted, or whatever the surrounding text is.

import { Stack } from '@/components/Stack';

<Stack direction="row" gap="lg" align="center">
  <Loading color="accent" label="Loading" />
  <Loading color="muted" label="Loading" />
  <span style={{ color: 'var(--fui-color-info)' }}>

Inline

Sits on the text baseline mid-sentence.

<p style={{ margin: 0 }}>
  Processing your request <Loading.Inline label="Processing" /> please wait…
</p>

Centered

Fills its container and centres in it.

<div
  style={{
    width: '200px',
    height: '100px',
    border: '1px dashed var(--fui-border)',
    borderRadius: 'var(--fui-radius-md)',

Screen

Covers the surface it sits on and names the wait.

<div
  style={{
    position: 'relative',
    contain: 'layout',
    width: '300px',
    height: '200px',

API

Component props
Prop
Type
Default
Description
sizeenumsmmdlgxlmdSize of the loading indicator
kindenumspinnerdotspulsespinnerWhich animation plays
labelstringLoading...Accessible label for screen readers
centeredbooleanfalseWhether to center the loading indicator in its container
fillbooleanfalseWhether to fill the parent container
overlaybooleanfalseWhether to show with a backdrop overlay
colorenumaccentcurrentmutedaccentColour. accent uses the theme accent, current inherits the surrounding text colour

Accessibility

  • Announced through role="status" with aria-live="polite"
  • label is what a screen reader reads — make it specific
  • Animation stops for prefers-reduced-motion

Guidance

Use when

  • Fetching or processing content
  • Waiting on an async action to come back
  • Buttons, forms, and page sections mid-request
  • The first paint of an app or page

Avoid when

  • You know the percentage — use Progress
  • You know the page shape — use Skeleton
  • AI reasoning states — use ThinkingIndicator

Next steps