Preloader Collection

Three preloader overlay animations — text reveal, staircase slide, and pixel dissolve — each revealing the content with its own signature exit once loading finishes.

Loading preview…

npx shadcn@latest add "https://webberui.com/r/preloader-collection.json?t=<install token>"

Playground

Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.

Animation stylevariant

Center labellabel

Progress percentageprogress

Column / cell baselinecolumns

<PreloaderCollection />

Installation

npx shadcn@latest add "https://webberui.com/r/preloader-collection.json?t=<install token>"

Or, once registries are configured in components.json, install it as @webberui/preloader-collection.

Usage

import { PreloaderCollection } from "@/components/ui/preloader-collection";

// Uncontrolled: shows on mount and exits automatically once minDuration has passed
<PreloaderCollection variant="staircase" label="WEBBER" />

// Controlled: you decide when it closes (for example, once data has loaded)
const [loading, setLoading] = React.useState(true);

<PreloaderCollection
  variant="pixel"
  loading={loading}
  label="Loading"
  onComplete={() => console.log("revealed")}
/>

Props

Prop	Type	Default	Description
`variant`	`"text" \| "staircase" \| "pixel"`	`"text"`	Animation style: text reveal / staircase slide / pixel dissolve
`loading`	`boolean`	—	Controlled visibility; the exit is triggered by `true→false`. When omitted, the component is uncontrolled
`minDuration`	`number`	`1400`	In uncontrolled mode, the minimum time it stays visible before exiting automatically (milliseconds)
`position`	`"fixed" \| "absolute"`	`"fixed"`	Overlay positioning: full screen, or snapped to the nearest positioned ancestor
`label`	`string`	`"Loading"`	Centered label text (the main subject for the `text` variant, a caption for the others)
`progress`	`number`	—	Progress percentage (0–100); when provided the number is shown, without affecting exit timing
`columns`	`number`	`6` / `14`	Number of columns for `staircase` (default 6) / cells per row for `pixel` (default 14)
`onComplete`	`() => void`	—	Callback after the exit animation has fully finished and the DOM has unmounted

How it works

Controlled and uncontrolled modes: without loading it is uncontrolled — the component covers the screen on mount, then exits automatically once minDuration has passed, which suits a simple entrance overlay. Passing loading hands control to the outside, usually bound to the loading state of data or routing; true→false plays the exit, reveals the content underneath, and calls onComplete once every animation has finished.
Three signature exits: text slides the whole panel upward while the label flickers character by character in a wave; staircase slices the overlay into several columns that slide up staggered by index into a staircase on exit; pixel tiles the overlay with near-square pixel cells sized to its dimensions, and on exit scans diagonally, shrinking cell by cell into a pixel dissolve. The centered loading motion of each (bouncing dots, equalizer, flickering pixel matrix) matches its own exit vocabulary.
Self-adjusting pixel grid: the pixel variant measures the overlay's width and height with ResizeObserver and derives the row count from columns so each cell comes out near square; the measurement happens in a layout effect before paint, so the cell count never jumps. Adjacent tiles are padded with a same-color outline to fill sub-pixel hairline seams, so no light leaks through while the overlay is up.
Positioning scope: position="fixed" covers the whole viewport, which suits a page-level preloader; position="absolute" covers only the nearest relative / absolute ancestor, which suits section-level loading (inside a card or a panel, say) — the demo uses this mode.
Progress display: when progress is passed, every variant shows the percentage number and updates aria-valuenow; progress is purely for display and announcement, while whether it exits is still decided by loading (or minDuration), so the two can be controlled independently.

Accessibility

With progress the overlay is role="progressbar" (carrying aria-valuemin/max/now), otherwise role="status" aria-live="polite", along with aria-busy and an aria-label; every tile and decorative motion is aria-hidden, so the screen reader hears the label and the progress only once.
When the user has "reduce motion" enabled at the system level, it switches to a static overlay showing only the label and the progress, and the exit is a plain fade out with no tile animation.
The overlay carries select-none and cursor-wait and blocks interaction with the layer underneath using solid tiles, so users cannot accidentally hit content that is not ready yet during loading.