docs / core / loading-overlay

LoadingOverlay

a dimming scrim with a centered spinner, over its parent while it loads or over the whole page.

intensity · recedesrsc · client

provenance

shaped from sisu-plus

layer

core / primitives

intensity

recedes · safe anywhere, including dense surfaces

composition

over a positioned panel or Card while its data loadscontain="viewport" for whole-page transitions, even over an open modalnot for button-level loading. Button has a status machinenot a Dialog scrim. it dims content, it does not trap focus

a11y

the spinner is a role="status" region announcing the label once · the visible caption is aria-hiddenjest-axe

dependencies

Spinner from the same package
live demo · try it out

content underneath, dimmed by the overlay.

Fetching courses
customize
variantspinner shape
sizespinner scale
toneaccent or inherited text color
labelannounced and shown as caption
blurbackdrop blur behind the scrim
usagecopy
import { LoadingOverlay } from "@usva-ui/react/primitives/loading-overlay";

<div className="relative">
  <LoadingOverlay label="Fetching courses" />
</div>

props

proptypedefaultnotes
contain"viewport" | "parent""parent"parent covers the nearest positioned ancestor and locks nothing. viewport locks body scroll, refcounted, and restores the exact overflow value it found.
labelstring"Loading"announced by the status region and repeated as a visible caption.
blurbooleantruebackdrop blur behind the scrim.
variant"ring" | "dots" | "bars" | "orbit""ring"forwarded to Spinner.
sizeSpinnerSize"lg"forwarded to Spinner.
toneSpinnerTone"accent"forwarded to Spinner.

get it

bun add @usva-ui/reactcopy
usagecopy
import { LoadingOverlay } from "@usva-ui/react/primitives/loading-overlay";

<div className="relative">
  <LoadingOverlay label="Fetching courses" />
</div>

<LoadingOverlay contain="viewport" label="Loading dashboard" />