❝Ossa loquuntur, dum carnem expectamus.❞ The bones speak while we wait for the flesh.

Minimal-effort skeleton loaders for React — wrap what you already render, and CSS Anchor Positioning keeps shimmers aligned to the real DOM. No sizing props, no skeleton stand-ins, no drift as your UI evolves.

View Live Demo →

Contents

1. Getting started
2. Palette
3. Placeholder
4. Depth
5. Recipes

For advanced topics, see the recipes directory.

Getting started

Install, wrap what you already render, and flip skeleton while data is loading. useBonework() inside lets descendants render safe fallbacks that vanish when real data lands:

pnpm add bonework

import { Bonework, useBonework } from "bonework";

const aed = new Intl.NumberFormat("en-AE", {
  style: "currency",
  currency: "AED",
});

type BalanceProps = { amount: number | null };
type WalletProps = { data: Wallet | null };

function Balance({ amount }: BalanceProps) {
  const bonework = useBonework();
  const formatted = amount != null ? aed.format(amount) : null;
  return <span>{bonework.placeholder(formatted, aed.format(0))}</span>;
}

export function Wallet({ data }: WalletProps) {
  return (
    <Bonework skeleton={!data}>
      <h1>{data?.name ?? "Placeholder name"}</h1>
      <Balance amount={data?.balance ?? null} />
    </Bonework>
  );
}

Two moving parts. <Bonework> wraps the real UI in a display: contents host, walks the rendered DOM in a useLayoutEffect, and paints shimmers over each target via CSS Anchor Positioning while skeleton is true. useBonework() reads that state so descendants render fallbacks (placeholder(actual, fallback)) that vanish once the skeleton drops.

Because Bonework operates on the real DOM — not on React elements — you don't need your children to forward ref/style/className. Wrap anything: native tags, third-party UI kits, portals. If it lands in the DOM, Bonework can anchor to it.

Palette

Bonework ships a neutral default ({ bone: "#e5e7eb", highlight: "#f3f4f6" }), so you can drop it in without wiring anything. Pass palette to align the shimmer with your design tokens — bone is the still band, highlight is the sweep:

<Bonework
  skeleton
  palette={{
    bone: theme.colour.surface.muted,
    highlight: theme.colour.surface.bold,
  }}
>
  ...
</Bonework>

The default is exported as defaultPalette if you want to spread over it.

Placeholder

useBonework() returns { skeleton, placeholder }. placeholder(actual, fallback) handles the common trap where a hard-coded default (data.balance ?? 0) leaks past resolution:

| actual | skeleton | Returns | | -------------------- | ---------- | ---------- | | present | either | actual | | null / undefined | true | fallback | | null / undefined | false | null |

Outside a <Bonework> the hook is still safe: placeholder just returns actual ?? null.

Depth

By default a single shimmer paints over each direct DOM child. For composed layouts — a row, a card — you usually want each leaf shimmering separately while wrapper gaps stay intact. Increase depth:

<Bonework skeleton palette={tokens} depth={2}>
  <div className="row">
    <img src="..." />
    <div>
      <strong>Name</strong>
      <p>Subline</p>
    </div>
  </div>
</Bonework>

depth={1} anchors the row. depth={2} anchors <img> and the inner <div>. Bump it further to descend deeper. Depth walks the rendered DOM, not the React element tree — so it works uniformly with plain tags, styled-components, third-party UI kits, and anything that ends up as real HTML.

Recipes

• Tuning — radius, duration, palette wiring.
• Testing — asserting on anchored elements and testing the hook.
• Browsers — support matrix and progressive-enhancement notes.
• API — full type reference.