Escape Hatches

AutoSkeleton's heuristics work well for most layouts, but sometimes you need to override the inferred skeleton type. Data attributes give you direct control.

data-skeleton-role

Force an element to be rendered as a specific skeleton type, regardless of what the heuristics infer.

tsx

<span data-skeleton-role="text">Custom widget text</span>

Supported Roles

Role	Skeleton Output
`text`	Horizontal bar(s) matching text dimensions
`image`	Solid block matching image dimensions
`icon`	Small square block
`button`	Inline block with fixed dimensions
`input`	Inline block with fixed dimensions

When to Use

Misclassified elements: If a custom component is being detected as the wrong type:

tsx

{/* This custom div looks like a button but AutoSkeleton thinks it's text */}<div data-skeleton-role="button" onClick={handleClick} className="custom-btn">  Click me</div>

Background image containers: Divs with CSS background images may not be detected as images:

tsx

{/* Force image skeleton for a CSS background container */}<div  data-skeleton-role="image"  style={{ backgroundImage: `url(${imageUrl})`, width: 300, height: 200 }}/>

SVGs that aren't icons: Large SVGs may be classified as icons due to the <svg> tag:

tsx

{/* This is a chart, not an icon */}<svg data-skeleton-role="image" width="400" height="300">  <ChartContent /></svg>

Contenteditable regions:

tsx

{/* Editable div that should skeleton as input */}<div data-skeleton-role="input" contentEditable style={{ minHeight: 100, border: '1px solid #ccc' }}>  {content}</div>

data-skeleton-ignore

Exclude an element from skeleton generation entirely. The element won't appear in the skeleton — it will be blank space.

tsx

<AutoSkeleton loading={loading}>  <div>    <h1>Page Title</h1>    {/* This toolbar won't appear in the skeleton at all */}    <div data-skeleton-ignore>      <ToolbarButtons />    </div>    <p>Content that will be skeletonized...</p>  </div></AutoSkeleton>

**Tip:** `data-skeleton-ignore` is included in the default `ignoreSelectors` config. You can add more custom selectors — see [Configuration](./04-configuration.md#ignoreselectors).

Comparison with Opt-Out

Attribute	Element During Loading	In Skeleton
`data-skeleton-role="..."`	Hidden	Shown as specified skeleton type
`data-skeleton-ignore`	Hidden	Not shown (blank space)
`data-no-skeleton`	Visible	Not shown (element itself is visible)

Use data-skeleton-role to fix misclassification
Use data-skeleton-ignore to hide from skeleton
Use data-no-skeleton to show during loading

Debugging Tips

If an element isn't rendering the skeleton type you expect:

Inspect the element's computed styles — display, cursor, width, height all affect scoring
Check if the element has text content — text signals boost text classification
Check element dimensions — very small elements may be classified as skip
Use data-skeleton-role to force the correct type as a quick fix