boneyard-vue

Pixel-perfect skeleton loading screens for Vue 3, extracted from your real DOM. No manual measurement, no hand-tuned placeholders.

Vue 3 port of boneyard-js by 0xGF. Core engine ported with permission under MIT license.

How it works

1. Wrap your component with <BoneyardSkeleton> and give it a name
2. Run npx boneyard-vue build — it snapshots the DOM and generates bones
3. Import the registry once — every skeleton auto-resolves

<script setup>
import { BoneyardSkeleton } from "boneyard-vue/vue";

const { data, isLoading } = useFetch("/api/post");
</script>

<template>
  <BoneyardSkeleton name="blog-card" :loading="isLoading">
    <BlogCard v-if="data" :data="data" />
  </BoneyardSkeleton>
</template>

npx boneyard-vue build

// main.ts — add once
import "./bones/registry";

Done. Every <BoneyardSkeleton name="..."> shows a pixel-perfect skeleton on load.

Install

npm install boneyard-vue

What it does

• Reads getBoundingClientRect() on every visible element in your component
• Stores positions as a flat array of { x, y, w, h, r } bones
• Renders them as gray rectangles that match your real layout exactly
• Responsive — captures at multiple breakpoints (375px, 768px, 1280px by default)
• Pulse animation shimmers to a lighter shade of whatever color you set
• Auto-detects dark mode (media query + .dark class)

Props

| Prop | Type | Default | Description | | ----------------- | --------------------------------- | ------------------------ | ----------------------------------- | | loading | boolean | required | Show skeleton or real content | | name | string | — | Unique name for this skeleton | | initial-bones | SkeletonResult | ResponsiveBones | — | Pre-generated bones | | color | string | rgba(0,0,0,0.08) | Bone fill color | | dark-color | string | rgba(255,255,255,0.06) | Bone color in dark mode | | animate | boolean | true | Pulse animation | | snapshot-config | SnapshotConfig | — | Control which elements are included |

Slots

| Slot | Description | | ---------- | ------------------------------------------ | | default | Your component — rendered when not loading | | fallback | Shown when loading and no bones available | | fixture | Mock content for CLI build mode capture |

Usage patterns

Direct import (tree-shakeable)

<script setup>
import { BoneyardSkeleton } from "boneyard-vue/vue";
</script>

Plugin (global registration)

// main.ts
import { createApp } from "vue";
import { BoneyardPlugin } from "boneyard-vue/vue";
import "./bones/registry";

const app = createApp(App);
app.use(BoneyardPlugin);
app.mount("#app");

Then use <BoneyardSkeleton> anywhere without importing.

Composable

<script setup>
import { useSkeleton } from "boneyard-vue/vue";

const { containerRef, activeBones, resolvedColor } = useSkeleton({
  name: "dashboard-chart",
});
</script>

<template>
  <div ref="containerRef">
    <!-- custom rendering with activeBones -->
  </div>
</template>

CLI

npx boneyard-vue build                    # auto-detect dev server
npx boneyard-vue build http://localhost:5173
npx boneyard-vue build --breakpoints 390,820,1440 --out ./public/bones

Options

| Flag | Default | Description | | -------------------- | -------------- | ------------------------------- | | --out <dir> | ./src/bones | Output directory | | --breakpoints <bp> | 375,768,1280 | Comma-separated viewport widths | | --wait <ms> | 800 | Extra ms after page load |

Fixtures

Provide mock content so the CLI can capture bones even without real data:

<BoneyardSkeleton name="user-card" :loading="isLoading">
  <UserCard v-if="user" :user="user" />

  <template #fixture>
    <UserCard :user="{ name: 'Jane Doe', avatar: '/placeholder.png' }" />
  </template>
</BoneyardSkeleton>

Credits

This project is a Vue 3 port of boneyard-js created by 0xGF. The core skeleton extraction engine (DOM walking, layout computation, responsive breakpoints) is ported directly from the original project. The Vue component layer, composable, plugin system, and security hardening are new additions.

License

MIT — see LICENSE