API Reference

Everything you can pass to <Skeleton> and the build CLI.

<Skeleton> props

loadingbooleanrequired

When true, shows the skeleton. When false, shows your real content.

childrenReactNoderequired

Your actual component. This is what boneyard reads to figure out where to put the skeleton rectangles.

namestringrequired

A unique name for this skeleton. The build CLI uses this to create the .bones.json file.
Example: name="blog-card" → generates blog-card.bones.json

initialBonesResponsiveBones

Optional manual override — pass a bones JSON file directly to a specific Skeleton. If you use the registry (import './bones/registry' in your app entry), you don't need this prop. The registry auto-resolves bones by name.

// Only needed if you're NOT using the registry import blogBones from '@/bones/blog-card.bones.json'

colorstringdefault: #e0e0e0

The color of the skeleton rectangles. Any hex color works. The pulse animation automatically shimmers to a lighter version of whatever color you set.

animatebooleandefault: true

The pulse animation. Set to false if you want static gray rectangles with no animation.

classNamestring

An extra CSS class on the wrapper div. Use it if you need to add margins, padding, etc.

fallbackReactNode

What to show if you haven't generated bones yet. You probably don't need this — just run the build command.

fixtureReactNode

Mock content rendered during npx boneyard-js build so the CLI can capture bone positions even when real data isn't available (e.g., behind authentication, user-specific data, or API-dependent content).

Only rendered when the CLI is running — never used in production.

fixture={ <BlogCard data={{ title: "Sample Post Title", excerpt: "Placeholder text for layout capture..." }} /> }

snapshotConfigSnapshotConfig

Controls how the build CLI extracts bones. See the "Hiding elements" section below for details.

Full example

app/blog/page.tsx

// Registry auto-resolves bones — no per-file JSON import needed
import { Skeleton } from 'boneyard/react'

function BlogPage() {
  const { data, isLoading } = useFetch('/api/post')

  return (
    <Skeleton
      name="blog-card"
      loading={isLoading}
      color="#d4d4d4"
    >
      {data && <BlogCard data={data} />}
    </Skeleton>
  )
}

Hiding elements from the skeleton

Sometimes you don't want everything to show up in the skeleton. Maybe you have icons, decorative elements, or a live widget that should always be visible. You can tell boneyard to skip them.

Pass a snapshotConfig prop to control what gets included:

Skip specific elements by CSS class or attribute

Use excludeSelectors — any CSS selector works. The element and everything inside it gets ignored.

example

<Skeleton
  name="dashboard"
  loading={isLoading}
  initialBones={dashBones}
  snapshotConfig={{
    excludeSelectors: [
      '.icon',                     // skip all icons
      '[data-no-skeleton]',         // skip anything with this attribute
      'svg',                        // skip all SVGs
    ]
  }}
>

Skip entire HTML tags

Use excludeTagsto skip every instance of a tag type. Good for nav bars and footers that shouldn't be part of the skeleton.

tsx

snapshotConfig={{
  excludeTags: ['nav', 'footer', 'aside']
}}

Mark elements in your JSX

The easiest way — add data-no-skeleton to any element you want to hide, then exclude it:

your-component.tsx

// This chart will always render, even during loading
<div data-no-skeleton>
  <LiveChart />
</div>

// Then in your Skeleton wrapper
snapshotConfig={{ excludeSelectors: ['[data-no-skeleton]'] }}

Other snapshot options

leafTags — Tags treated as one solid block (default: p, h1–h6, li, tr). Add span if your text renders inside span wrappers.
captureRoundedBorders — Set false if your cards use shadows instead of borders (default: true).

Build command

This is how you generate the bones JSON files. Run it with your dev server running:

bash

npx boneyard-js build

It opens a headless browser, visits your app, finds every <Skeleton name="...">, measures the layout at different screen sizes, and saves the result as JSON files you can import.

urlpositionaldefault: auto-detected

The URL(s) to visit. If you don't pass one, it scans common dev ports (3000, 5173, 4321, 8080…) and uses the first one that responds.

--breakpointsstringdefault: 375,768,1280

Screen widths to capture at, comma-separated. The defaults cover mobile, tablet, and desktop.

--waitnumberdefault: 800

How long to wait (in ms) after the page loads before capturing. Increase this if your components take a while to render.

--outstringdefault: ./src/bones

Where to save the JSON files. Defaults to src/bones/ if you have a src/ folder, otherwise ./bones/.

Examples

bash

# Auto-detect server, default breakpoints
npx boneyard-js build

# Specific page
npx boneyard-js build http://localhost:3000/dashboard

# Multiple pages at once
npx boneyard-js build http://localhost:3000 http://localhost:3000/profile

# Custom breakpoints + output dir
npx boneyard-js build --breakpoints 390,820,1440 --out ./public/bones

Playwright is included as a dependency. On first run you may need to install the browser: npx playwright install chromium