API

skelly(element: HTMLElement | null, options?: SkellyOptions) => () => void

Replaces the targeted container elements content with a pixel-accurate skeleton overlay. It returns a callback function: release(). Call this release callback as soon as data loading is finished to fade out the skeleton and restore the real component tree.

options.visual

Specifies the skeleton animation style. Accepts "shimmer" (gradient sweep), "pulse" (opacity fade), "optimistic" (reconcile layout values), or "static" (solid color block). Defaults to "shimmer".

options.preset

Accepts "dashboard" | "article" | "feed" | "profile" | "generic". Pre-draws a template layout immediately, ideal for when children subtrees are empty during initial server mounts.

options.rows

Configures the number of text rows in the generic skeleton — the one used by preset="generic" and by the fallback when a container has nothing measurable in it. Measured layouts always derive their own line count from the real markup.

options.media

Defines image rendering styles. Accepts "block" (gray background), "dominant-color" (fades in the dominant color of the source image), or "blurhash". Defaults to "block".

options.structure

Controls how structural parents — cards, panels, sections — are compiled. "leaves" (default) lets a parent that holds measurable content emit nothing of its own, so the skeleton reads as its contents. "surface" keeps the parent as a flat, unanimated backing plate behind its children, preserving the card outline.

options.cache

Compiled layouts are cached per container, keyed on its markup and measured box. Set to false to re-measure on every mount. Compiled specs are absolute pixel geometry, so call clearSpecCache() after anything that changes geometry without changing markup — a font load, a theme swap, a container resize.

data-skelly-ignore

Put it on any element that should never become a skeleton shape. Decoration is skipped automatically — anything blurred, and aria-hidden elements lifted out of flow with no text of their own, which is what a background orb or glow looks like. An aria-hidden icon sitting in flow next to a label is still treated as content. Use the attribute for whatever the heuristics miss.

options.name

A stable identity for a layout. With one, skelly measures the real content when it renders, stores it per viewport bucket, and replays it on later loads — including before this component has ever mounted. See Learned skeletons.

learnLayout(element, options) · recallSpec(name, options)

The manual halves of the same loop, for vanilla usage. learnLayout() measures what is on screen and stores it under options.name; recallSpec() returns what was learned for the current viewport, or null. The React wrapper calls both for you.

exportLearnedSpecs() · importLearnedSpecs() · clearLearnedSpecs()

Move learned layouts in and out as { "name@breakpoint": spec }. Export from a browser that has used the app, commit the result, and render it with <SkellySpecs> so first-time visitors get real skeletons too.

snapshot(route: string, options?: SnapshotOptions) => Promise<void>

Writes a route’s skeleton spec into a JSON file for server inlining. Pass spec with a layout you compiled in the browser via measureLayout() and it is written verbatim; without one, snapshot() infers a built-in preset from the route path. It does not run a browser itself.