API Reference
AutoSkeleton Component
The main component exported from the package.
tsx
import { AutoSkeleton } from 'auto-skeleton-react';Props
| Prop | Type | Required | Description |
|---|---|---|---|
loading | boolean | Yes | Controls skeleton visibility. true shows skeleton, false shows content. |
children | React.ReactNode | Yes | The content to wrap. Rendered hidden during loading for measurement. |
config | Partial<SkeletonConfig> | No | Override default configuration options. |
Usage
tsx
<AutoSkeleton loading={isLoading} config={{ animation: 'pulse' }}> <YourComponent /></AutoSkeleton>SkeletonConfig
Configuration interface for customizing skeleton behavior and appearance.
tsx
import type { SkeletonConfig } from 'auto-skeleton-react';Properties
| Property | Type | Default | Description | ||
|---|---|---|---|---|---|
animation | `'pulse' \ | 'shimmer' \ | 'none'` | 'pulse' | Animation applied to skeleton elements |
baseColor | string | '#e0e0e0' | Background color of skeleton blocks | ||
highlightColor | string | '#f5f5f5' | Highlight color for animations | ||
borderRadius | number | 4 | Border radius (px) for skeleton blocks | ||
minTextHeight | number | 12 | Minimum height (px) to classify as text | ||
minImageSize | number | 32 | Minimum dimension (px) to classify as image | ||
iconMaxSize | number | 48 | Maximum dimension (px) for icon detection | ||
maxDepth | number | 10 | Maximum DOM traversal depth | ||
ignoreSelectors | string[] | ['.no-skeleton', '[data-skeleton-ignore]'] | CSS selectors to exclude from skeleton |
Example
tsx
const config: Partial<SkeletonConfig> = { animation: 'pulse', baseColor: '#f0f0f0', borderRadius: 8, maxDepth: 15, ignoreSelectors: ['.no-skeleton', '[data-skeleton-ignore]', '.custom-ignore'],};<AutoSkeleton loading={true} config={config}> <MyComponent /></AutoSkeleton>SkeletonNode
Represents a node in the skeleton blueprint tree. Useful for advanced debugging or custom renderers.
tsx
import type { SkeletonNode } from 'auto-skeleton-react';Properties
| Property | Type | Description |
|---|---|---|
type | string | Element role (see types below) |
rect | { x, y, width, height } | Position and dimensions |
borderRadius? | number | Border radius |
display? | string | CSS display value |
gap? | string | CSS gap value |
children? | SkeletonNode[] | Child nodes |
lines? | number | Line count (multi-line text) |
tagName? | string | HTML tag name (table elements) |
passthrough? | boolean | Whether to render original HTML |
passthroughHtml? | string | Original HTML content |
preservedStyles? | object | CSS styles preserved from original |
Node Types
| Type | Description |
|---|---|
text | Text content |
image | Images and background images |
icon | Small square SVGs/icons |
button | Interactive buttons |
input | Form inputs, textareas, selects |
container | Layout wrapper with children |
skip | Tiny spacer elements (not rendered) |
passthrough | Preserved original HTML |
table | HTML table element |
thead | Table head |
tbody | Table body |
tr | Table row |
th | Table header cell |
td | Table data cell |
Data Attributes
These HTML attributes control skeleton behavior on specific elements.
| Attribute | Effect |
|---|---|
data-no-skeleton | Element stays visible during loading (not skeletonized) |
data-skeleton-ignore | Element is skipped entirely from skeleton generation |
data-skeleton-role | Forces a specific skeleton type (e.g., "text", "image", "button") |
CSS Classes
| Class | Effect |
|---|---|
.no-skeleton | Same as data-skeleton-ignore — element skipped from skeleton |
See Opt-Out and Escape Hatches for details.