v0.0.5 — Zero-config runtime DOM scanning. No CLI, no config files. →
API Reference

API Reference

React — @auto-skeleton/react

<AutoSkeleton>

The main component. Wraps any subtree and replaces it with a skeleton overlay when loading is true.

import { AutoSkeleton } from "@auto-skeleton/react";
 
<AutoSkeleton
  id="unique-id"
  loading={boolean}
  className="..."
  options={{ ... }}
>
  {children}
</AutoSkeleton>

Props

PropTypeRequiredDescription
idstring✅Unique cache key. Must be unique per instance on the page.
loadingboolean✅When true, shows the skeleton overlay.
classNamestringCSS class added to the root wrapper <div>.
optionsAutoSkeletonOptionsFine-tune scan and animation behaviour.

AutoSkeletonOptions

OptionTypeDefaultDescription
animation"wave" | "pulse" | "none""wave"Skeleton animation style.
debugbooleanfalseOutline detected bones with dashed borders for debugging.
watchbooleantrueRe-scan when layout changes while not loading.
watchDebounceMsnumber120Debounce delay (ms) for watcher-triggered re-scans.
cachebooleantrueCache bones in memory and sessionStorage.
minSizenumber8Minimum element dimension (px) to generate a bone for.
ignoreSelectorsstring[][]CSS selectors for elements to skip during scan.

Vue 3 — <AutoSkeleton>

The Vue 3 component. Works identically to the React version — wrap any template subtree, pass loading.

<script setup lang="ts">
import { AutoSkeleton } from "@auto-skeleton/vue";
import "@auto-skeleton/vue/styles.css";
</script>
 
<template>
  <AutoSkeleton id="unique-id" :loading="loading" :options="{ animation: 'wave' }">
    <slot />
  </AutoSkeleton>
</template>

Props

PropTypeRequiredDescription
idstring✅Unique cache key per instance.
loadingboolean✅Shows skeleton overlay when true.
optionsAutoSkeletonOptionsSame options object as React — see below.

Vue 3 — useAutoSkeleton

Low-level composable for custom overlay integrations.

import { useAutoSkeleton } from "@auto-skeleton/vue";
 
const { rootRef, bones, shouldShow, animation, debug } = useAutoSkeleton(
  toRef(props, "id"),
  toRef(props, "loading"),
  toRef(props, "options")
);

Parameters

ParameterTypeDescription
idRef<string>Unique cache key.
loadingRef<boolean>Controls when bones are active.
optionsRef<AutoSkeletonOptions | undefined>Optional configuration.

Returns

PropertyTypeDescription
rootRefRef<HTMLElement | null>Attach to your container element.
bonesComputedRef<Bone[] | null>Detected bones, or null before first scan.
shouldShowComputedRef<boolean>true when loading and bones are ready.
animationComputedRef<string>Resolved animation ("wave" default).
debugComputedRef<boolean>Resolved debug flag.

React — useAutoSkeleton

Low-level hook for custom integrations. Returns the scan state and a ref to attach to your container.

import { useAutoSkeleton } from "@auto-skeleton/react";
 
function MyComponent({ loading }: { loading: boolean }) {
  const { ref, bones, isScanning } = useAutoSkeleton({
    id: "my-component",
    loading,
    options: { animation: "pulse" },
  });
 
  return <div ref={ref}>{/* your content */}</div>;
}

Parameters

ParameterTypeRequiredDescription
idstring✅Unique cache key.
loadingboolean✅Controls when bones are active.
optionsAutoSkeletonOptionsSame options as <AutoSkeleton>.

Returns

PropertyTypeDescription
refRefObject<HTMLDivElement>Attach to the container element you want scanned.
bonesBone[]Current array of detected bones.
isScanningbooleantrue while a scan is in progress.

Lit & Web Components — @auto-skeleton/lit

<auto-skeleton>

A native custom element. Works in any framework or vanilla JS. Registered automatically on import.

import '@auto-skeleton/lit';
<auto-skeleton skeleton-id="profile" loading>
  <user-profile></user-profile>
</auto-skeleton>

Attributes & properties

NameTypeRequiredDescription
skeleton-idstring (attribute)✅Unique cache key. Maps to the skeletonId JS property.
loadingboolean (property)✅When true, shows the skeleton overlay. Presence of the attribute also sets true.
optionsAutoSkeletonOptions (property only)Fine-tune scan and animation behaviour. Set via JS or Lit property binding.

Use .options (property binding) rather than an attribute, as the options object cannot be serialised to a string attribute. In Lit: .options=${{ animation: "pulse" }}.

AutoSkeletonOptions

Same shape as the React package:

OptionTypeDefaultDescription
animation"wave" | "pulse" | "none""wave"Skeleton animation style.
debugbooleanfalseOutline detected bones with dashed borders.
watchbooleantrueRe-scan when layout changes while not loading.
watchDebounceMsnumber120Debounce delay (ms) for watcher-triggered re-scans.
cachebooleantrueCache bones in memory and sessionStorage.
minSizenumber8Minimum element dimension (px) to generate a bone.
ignoreSelectorsstring[][]CSS selectors for elements to skip during scan.

Cache utilities

import { clearCachedBones, clearAllCachedBones } from '@auto-skeleton/lit';
 
clearCachedBones('profile');   // clear one cache entry
clearAllCachedBones();         // clear all entries

Core — @auto-skeleton/core

Framework-agnostic scanner. Used internally by both packages. Import directly for custom integrations.

import { scanBones } from '@auto-skeleton/core';
 
const bones = scanBones(containerElement, {
  minSize: 8,
  ignoreSelectors: ['.ad'],
});

scanBones(root, options?)

ParameterTypeDescription
rootHTMLElementThe element to scan. Children and shadow DOM are traversed recursively.
options.minSizenumberMinimum bone dimension in px. Default 8.
options.ignoreSelectorsstring[]Elements matching these selectors are skipped.

Returns Bone[] — an array of { x, y, width, height, radius, kind } objects positioned relative to root.

How It WorksData Attributes