Loading state

A pixel-grid loader with a shimmering label and a live elapsed timer for long-running work.

Churning0.0s

Installation

$Terminal

npx shadcn@latest add https://sdk-components.thesqd.com/r/loading-state.json

Usage

Import the master file and pass `pattern`, `tone`, and a `label`. The elapsed timer starts on mount.

TSImport

import { LoadingState } from "@/components/ui/loading-state";

TSExample

import { LoadingState } from "@/components/ui/loading-state";

export function Example() {
  return <LoadingState label="Churning" pattern="drive" />;
}

Composition

Anatomy of the LoadingState primitive.

LoadingState                      (single component — pass everything as props)
├── pattern="drive | dots | orbit"     (cell animation)
├── tone="brand | violet | coral | amber | magenta | plum | muted"
├── size="sm | default | lg"           (3px · 4px · 6px cells)
├── label={<ReactNode>}                (shimmering status text)
└── showElapsed={boolean}              (live mono timer, on by default)

LoadingStateGrid                  (the bare 3×3 grid, exported separately)
├── pattern="drive | dots | orbit"
└── size="sm | default | lg"

Drive

Square cells with a chevron wavefront driving right. The 650ms cycle is shorter than the sweep, so two fronts are always in flight.

Churning0.0s

Dots

The same wavefront rendered with circular cells.

Churning0.0s

Orbit

A comet lapping the grid perimeter on a 950ms cycle. The center cell stays dark.

Churning0.0s

Tones

Brand palette tints — the cells and the label shimmer both pick up the tone.

Churning0.0s

Rendering0.0s

Retrying0.0s

Reconciling0.0s

Transcoding0.0s

Archiving0.0s

Sizes

Three grid scales: `sm` (3px cells), `default` (4px), `lg` (6px).

Small0.0s

Default0.0s

Large0.0s

Without the timer

Set `showElapsed={false}` for work whose duration you don't want to advertise.

Churning

In a card

Dropped into a placeholder surface while the real content loads.

Loading activity0.0s

API Reference

Props exposed by the LoadingState and LoadingStateGrid components.

LoadingState

Prop	Type	Default	Description
`label`	ReactNode	"Churning"	Status text. Painted with a shimmering gradient that sweeps through the active tone.
`pattern`	"drive" \| "dots" \| "orbit"	"drive"	Cell animation. `drive` is a square chevron wavefront, `dots` the same wavefront with round cells, `orbit` a comet lapping the perimeter.
`tone`	"brand" \| "violet" \| "coral" \| "amber" \| "magenta" \| "plum" \| "muted"	"muted"	Tint for both the cells and the label shimmer. The default `muted` reads `--muted-foreground`, matching the grey on a Timer card; the rest are Squad brand hexes.
`size`	"sm" \| "default" \| "lg"	"default"	Grid scale — 3px, 4px, or 6px cells with matching gaps.
`showElapsed`	boolean	true	Renders a live elapsed timer in mono tabular figures, formatted `1.4s` / `2m 3.1s`. The clock is read each tick, so a throttled tab doesn't under-report.
`className`	string	—	Extend or override the root layout classes.

LoadingStateGrid

Prop	Type	Default	Description
`pattern`	"drive" \| "dots" \| "orbit"	"drive"	Same pattern vocabulary as `LoadingState`.
`size`	"sm" \| "default" \| "lg"	"default"	Grid scale.
`className`	string	—	Extend the grid classes. Note the cell fill reads `--sqd-ls-tone`, which `LoadingState` sets — standalone grids inherit the muted default.