Bruno DelorenceBruno
Appearance
Appearance

Choose your reading theme.

Contact

Auto skeleton

New

A loading wrapper that reads its skeleton from the content’s own shape, shimmers it in sync, then reveals each piece with a soft wipe.

auto-skeleton/auto-skeleton.tsx
Live · interactive

An article title goes here

A paragraph of the story’s opening lines runs here, about as long as the real one, so the lines it wraps into are the lines the reader will see when the text arrives, give or take a word at the end of each line, and the card keeps its height.

  • Wait, what does it read to know the size?
  • it draws your sample data unseen
  • then reads where each part sits and draws a bone in its place while the data loads
  • Eerie
  • bones usually are
Visits10,000+10%
Signups1,000+1%
Churn1.0%-0.1%
Revenue$1.0k+10%
  • Full nameA line of their last message, cut short here
  • Full nameAnother message preview that runs past the edge
Song titleArtist name
1:00
Portfolio$0,000.00-0.00%
  • AAAToken$0,000.00
  • BBBToken name$0,000.00
  • CCCToken$0,000.00

Loading

The live component, numbered part by part. Every measurement is read from it as it is drawn. Point at a row to outline its part, or at a part to find its row.

The choices it offers, each value drawn live and the default marked, with how to pick one.

When to use

  • Cards, lists and panels whose data comes from the network and takes long enough to notice, from about a fifth of a second to a few seconds.
  • Layouts you already render with placeholder data: the wrapper reads the skeleton from them, so it never drifts from the real component.
  • Dashboards and feeds where several pieces load on their own: each frame reveals when its own data lands, and every skeleton shimmers on the same clock.
  • Content whose shape is known before its words: a stat, a message, a track, a row with an avatar.

When not to use

  • Data that is there at render time, on the server or from a cache: render it. The wrapper shows it at once anyway, but it is a wrapper for nothing.
  • Loads under about 120 ms. The skeleton never shows (showAfter), so there is nothing to gain; leave the content as it is.
  • Waits with no known shape (a search with no results yet, an upload): use a spinner or a progress bar.
  • Long operations with progress to report, or that can fail and retry: show the progress and the error, not bones.
  • Content whose size depends on its real data so much that a placeholder can’t stand for it (a chart’s axis, a free-form article). Draw a simpler fixed skeleton.

Placeholder data

The skeleton is as good as the placeholder it is read from.

  • Give the placeholder the same rows as the real data: the same number of messages, holdings, tiles.
  • Use words of about the real length, so lines wrap where the real ones will and the card keeps its height.
  • Leave fixed chrome as it is: labels like “Portfolio” can be the real words, they are drawn as bones all the same.

Each one drawn with the component itself, used well or badly.

The placeholder is never seen or read, but it decides the skeleton.

  • Keep each placeholder string within a few characters of the real one.
  • Mark an element with data-skeleton="skip" when it should not be drawn (a decoration inside a bubble), "block" to draw it whole.

You can add this component with the shadcn CLI or by hand:

Into components/auto-skeleton of any React project, with no setup:

Terminal
npx shadcn@latest add https://brunodelorence.com/r/auto-skeleton.json

Either way it needs React 19.2 and a bundler that supports CSS Modules, such as Next.js or Vite. It has a dark colour scheme: it follows your page’s color-scheme, light unless the page sets one, or its colorScheme prop, with nothing to configure. Browsers without light-dark() show it light.

Usage

profile.tsx
import { AutoSkeleton } from './auto-skeleton';const PLACEHOLDER = { name: 'Full name', role: 'Their role, here', plan: 'Plan' };export function Profile({ user }: { user?: User }) {  return (    <AutoSkeleton loading={!user} onRevealed={() => console.log('shown')}>      <article className="card">        <Avatar src={user?.avatar} />        <h3>{(user ?? PLACEHOLDER).name}</h3>        <p>{(user ?? PLACEHOLDER).role}</p>        <span className="chip">{(user ?? PLACEHOLDER).plan}</span>      </article>    </AutoSkeleton>  );}

Each state below is a live instance, locked so you can study it.

The pieces it is built from, each with its measurements read live.

Wrap any piece of interface and give it placeholder data while it loads: the wrapper renders it invisibly, measures every leaf (each line of text as wide as its words, every image, icon, field, bubble and button with its own corner radius) and draws a skeleton in exactly that shape, keeping the cards and tiles around them as they are. The bones shimmer as one diagonal band, in sync across every frame on the page. When the data lands, each piece wipes in from the left behind a soft edge while its bone wipes out, top to bottom. Content rendered with its data shows at once, data that comes back quickly shows with no skeleton at all, and an image keeps its bone until it has loaded. The gallery loads seven cards (stats, a chat, a player, a list of people, an article with its photo, a portfolio and a photo strip), each with its own latency; Reload fetches them again.

  • The children are always rendered, in their place, with whatever data the caller has: the real data, or a placeholder of the same shape. While loading they are visibility: hidden and inert, still laid out, so they set the frame’s size and nothing moves when the real content arrives.
  • The skeleton is read from that invisible DOM in a layout effect, with no markers and no build step, and again on every resize (a ResizeObserver) and once the fonts are ready. A text node becomes one bar per line from a Range’s client rects, as wide as its words, 0.75 of its font size tall, clipped to its box when it ends in an ellipsis. An image, SVG, canvas, field, or an element that paints a background around nothing but inline text (a bubble, a button, a chip, an avatar with initials) becomes one block with its computed border radius. An element that paints around other pieces is a surface, drawn with its own background, border, radius and shadow, so the card and its tiles stay as they are.
  • Overrides are data attributes: `data-skeleton="skip"` leaves an element out, `"block"` draws it as one block, `"keep"` draws it as a surface.
  • Bones are translucent ink (7% on light, 7.5% on dark), so they read on any surface. The sweep is one 105° band that crosses each frame every 1.6 s: every bone clips a frame-sized gradient placed back by its own offset, moved by a transform on the compositor, so all of them show slices of the same band. The animation’s negative delay is the page clock modulo 1.6 s, so frames that started at different times shimmer in step. `shimmer="pulse"` breathes the bones between 100% and 45% instead.
  • Bones fade in over 200 ms only after `showAfter` (120 ms): if the data lands sooner, the content shows at once with no skeleton and no reveal. Content that was never loading, as when it was rendered on the server with its data, shows at once too.
  • Revealing, every piece is animated with the Web Animations API before the first paint, staggered by where it is: 85% by its height in the frame, 15% by its offset along the line, over `stagger` (360 ms) in all. Each one runs for `duration` (320 ms) on cubic-bezier(0.22, 0.61, 0.36, 1).
  • The wipe is a registered <length-percentage>, --wipe, inside two mask gradients: the content is opaque up to 32 px before it and sharpens from a 4 px blur, the bone is the reverse, so one soft 32 px edge runs left to right and the bar seems to turn into the words. `reveal="blur"` fades each piece in from an 8 px blur, `"fade"` from transparent, `"none"` swaps at once.
  • An image that is still loading keeps its bone, and both animations wait for its load event. The frame is shown once every animation has finished, and calls onRevealed.
  • The gallery is three columns of cards (one column of four under 760 px), each in its own frame with its own latency, from 0.9 to 1.7 s. While on screen and untouched, a demo pointer types a reply into the chat, plays the track and reloads; any press or key hands it to the reader for good.
  • Under reduced motion the bones hold still (no sweep, no pulse, no fade-in) and the content shows at once.
PropTypeDefaultDescription
loadingboolean—True holds the skeleton, false reveals the content. Required with children. On the gallery it forces every card.
childrenReactNode—The content to load, given its placeholder data while loading. Without children, AutoSkeleton shows its gallery of cards.
reveal'wipe' | 'blur' | 'fade' | 'none''wipe'How each piece comes in: a soft 32 px wipe from the left with a 4 px blur, a blur from 8 px, a fade, or at once.
shimmer'sweep' | 'pulse' | 'none''sweep'How the bones move while loading: one diagonal band in sync across every frame, a pulse, or still.
staggernumber360Ms from the first piece’s reveal (top left) to the last one’s (bottom right).
durationnumber320Ms each piece’s reveal takes.
showAfternumber120Data that arrives sooner than this, in ms, shows at once, with no skeleton and no reveal.
announcebooleantrueSay “Loading” and “Loaded” in a polite live region. Turn it off when a page speaks once for many frames.
onRevealed() => void—Called once every piece is shown (on the gallery: every card).
autoplaybooleantrueThe gallery: load once on screen and let a demo pointer try it. False shows the cards loaded at once (Reload still loads them).
colorScheme'light' | 'dark' | 'system''system'The gallery: forces a scheme, or follows the page’s color-scheme.
classNamestring—Extra classes for the frame, or the gallery’s stage.

While loading

  • The frame is aria-busy and its content inert and hidden: placeholder data is never focused or read.
  • The skeleton is aria-hidden. One polite status says “Loading”, then “Loaded”.

Motion

  • Under reduced motion the bones hold still and the content shows at once, with no wipe or blur.

In this build

  • While loading, the frame is aria-busy and its content is visibility: hidden and inert: neither the keyboard nor a screen reader reaches placeholder data. The skeleton is aria-hidden.
  • A polite status says “Loading”, then “Loaded” once every piece is shown; the gallery speaks once for all its cards.
  • The cards are real: the chat’s reply is a labelled field with a Send button, playback is a progressbar with its time as text and a Play/Pause button, the drawn photos are images with a description.
  • Focus shows as a blue ring on every control; the demo pointer is decorative and stops for good at the first press or key.
  • Under reduced motion there is no shimmer and no reveal: the bones hold still and the content shows at once.

The complete source behind this demo. Open source under the MIT license, © 2026 Bruno Delorence: copy it, change it, ship it.

auto-skeleton.tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { useEffect, useEffectEvent, useRef, useState, type ReactNode } from 'react';import { Icon } from './art';import {  ARTICLE,  ARTICLE_PLACEHOLDER,  ArticleCard,  CHAT,  CHAT_PLACEHOLDER,  ChatCard,  PEOPLE,  PEOPLE_PLACEHOLDER,  PeopleCard,  PHOTOS,  PhotosCard,  PLAYER,  PLAYER_PLACEHOLDER,  PlayerCard,  PORTFOLIO,  PORTFOLIO_PLACEHOLDER,  PortfolioCard,
skeleton.tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import {  useEffect,  useLayoutEffect,  useRef,  useState,  type CSSProperties,  type ReactNode,} from 'react';import styles from './auto-skeleton.module.css';/* * Skeleton frame: the loading state of any piece of interface, drawn from the piece itself. * * - The children are always rendered, in their place. While loading they hold placeholder data *   (whatever the caller passes them before the real data is there) and are invisible *   (visibility: hidden, and inert), but still laid out, so they set the frame's size and can be *   measured. Nothing moves when the real content arrives. * - The skeleton is read from that invisible DOM, with no markers and no build step. Every leaf *   becomes a bone at its exact place: a line of text becomes a bar as wide as its words on that *   line (one per line, from a Range's client rects) and three quarters of its font size tall; an
cards.tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { CoinMark, Face, Icon, Landscape, Lighthouse, type Coin, type Scene } from './art';import styles from './auto-skeleton.module.css';/* * The gallery's cards. Each one draws whatever data it is given: the real data once it has * arrived, or, while it loads, its placeholder, which has the same shape (the same rows, words of * about the same length). The skeleton frame around it reads its skeleton from that placeholder. * Nothing here knows about skeletons. *//* Stats */type Stat = { label: string; value: string; change: string; up: boolean };export type StatsData = Stat[];export const STATS: StatsData = [  { label: 'Visitors', value: '12,480', change: '+12%', up: true },  { label: 'Signups', value: '1,204', change: '+4%', up: true },  { label: 'Churn', value: '2.1%', change: '-0.3%', up: false },  { label: 'Revenue', value: '$9.6k', change: '+18%', up: true },
art.tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.import { useId, type ReactNode } from 'react';/* * Everything the gallery's cards show that is not text, drawn here: the landscapes of the article * and the photo strip (gradient skies, layered hills and water in SVG), the token coins, the * avatars, the album cover's colours and the player's icons. No photos, no icon set. */export type Scene = 'tide' | 'coast' | 'dusk' | 'mist' | 'lake' | 'glacier' | 'forest';type Palette = {  sky: [string, string];  sun?: string;  far: string;  near: string;  water?: [string, string];};const SCENES: Record<Scene, Palette> = {  tide: {    sky: ['#2b3a55', '#d9a77f'],    sun: '#ffd9a8',
demo-pointer.tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import type { CSSProperties, Ref } from 'react';/* * The demo's pointer, and the steps that move it. A demo is a script of awaited steps: wait, or * glide the pointer somewhere. Stopping the demo (the reader takes over, or it scrolls away) ends * the step in progress at once: its promise rejects, which ends the script right there, and the * pointer fades out. * * Each glide is a curved flight played by the Web Animations API, so nothing runs frame by frame. * The points of the flight are handed to whoever wants to move along with it (nothing here uses * them yet). The arrow and the hand are HTML boxes * that swap by their visibility: a change of style inside an SVG would lay the SVG out again. */export type Point = { x: number; y: number };/** A glide's path and timing, for an animation that plays along with it. */export type Flight = { points: Point[]; timing: KeyframeAnimationOptions };export type Demo = {
use-autoplay.ts
// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { useCallback, useEffect, useRef, useState } from 'react';/* * When a demo may play on its own: while part of it is on screen and the tab is visible, never * under reduced motion, and never again once the reader has used it: `take()` hands it to the * reader for good (until the component mounts again). It also tells whether the element is on * screen in a visible tab, and whether the reader prefers reduced motion. */export function useAutoplay<T extends HTMLElement>() {  const ref = useRef<T>(null);  const [visible, setVisible] = useState(false);  const [reduced, setReduced] = useState(true);  const [taken, setTaken] = useState(false);  useEffect(() => {    const element = ref.current;    if (!element) return;    let onScreen = false;    const update = () => setVisible(onScreen && !document.hidden);    const observer = new IntersectionObserver(
auto-skeleton.module.css
/* Auto skeleton (auto-skeleton.tsx, skeleton.tsx): a masonry of cards on a quiet stage, each one   loading behind a skeleton read from its own shape, then revealed piece by piece.   The skeleton. Bones are translucent ink (7% on light, 7.5% on dark), so they read on the card   and on any tile inside it. The shimmer is one diagonal band (105°) that crosses the whole frame   every 1.6 s: each bone holds a frame-sized gradient placed back by its own --x and --y, moved   by a transform, so every bone shows its slice of the same band.   The reveal. --wipe is a registered length that the script animates per piece (Web Animations   API): the content's mask is opaque up to 32 px before it, the bone's mask is the reverse, so a   soft 32 px edge runs left to right over each piece while its content sharpens from 4 px of blur.   Colours are the tokens below, light-dark(light, dark): the component takes the color-scheme it   inherits from the page, or the one its colorScheme prop sets. */@property --wipe {  syntax: '<length-percentage>';  inherits: false;  initial-value: 0%;}.root,.frame {  --bone: light-dark(rgb(0 0 0 / 0.07), rgb(255 255 255 / 0.075));