Skeleton

A skeleton screen is a low-fidelity placeholder that gradually loads into real content, giving users a visual cue that content is on its way.

Usage

forge-skeleton shapes itself to match the content it’s standing in for through text, avatar, listItem, chip, button, and formField, plus stretch. Use it whenever the size and shape of the incoming content is already known; when it isn’t, use a linear or circular progress indicator, or a busy indicator for a full-page load, instead.

Rules

Use skeleton loading when the size and shape of the incoming content is already known and the wait is longer than a second.

Match each skeleton shape to the specific piece of content it stands in for.

For a list, two or three skeleton items are enough — they don't need to match the final loaded count.

Don't

Don't use a skeleton when the content's eventual size or shape is unknown — use a progress indicator instead.

Don't leave a skeleton on screen once its real content is ready — swap it out immediately.

Don't mix skeleton loading and a spinner for the same piece of content.

Basic usage

The default skeleton renders as a generic block; set a shape attribute to match specific content instead.

A generic skeleton block.

<forge-skeleton>
</forge-skeleton>

Profile layout

Combine avatar and text skeletons to stand in for a profile-style layout while its real content loads.

An avatar paired with text skeletons for a profile card.

<div style="width: 200px">
  <forge-skeleton avatar>
  </forge-skeleton>
  <forge-skeleton text>
  </forge-skeleton>
  <forge-skeleton text>
  </forge-skeleton>
  <forge-skeleton text style="width: 75%;">
  </forge-skeleton>
</div>

List

Set listItem to match the height and spacing of a real list row.

A few list-item skeletons standing in for rows that haven't loaded yet.

<div style="width: 200px">
  <forge-skeleton list-item>
  </forge-skeleton>
  <forge-skeleton list-item>
  </forge-skeleton>
  <forge-skeleton list-item>
  </forge-skeleton>
</div>

Matching other components

Set chip, button, or formField to match the shape of those specific components while their real content loads.

Form field

Form-field skeletons standing in for fields that haven't loaded yet.

<div style="width: 200px">
  <forge-skeleton form-field>
  </forge-skeleton>
  <forge-skeleton form-field>
  </forge-skeleton>
  <forge-skeleton form-field>
  </forge-skeleton>
</div>

Chips

Chip skeletons standing in for chips that haven't loaded yet.

<div style="width: 200px">
  <forge-skeleton chip>
  </forge-skeleton>
  <forge-skeleton chip>
  </forge-skeleton>
  <forge-skeleton chip>
  </forge-skeleton>
</div>

Skeletons are used to provide a placeholder for content that is loading. They have various styles to represent different types of content.

import "@tylertech/forge/skeleton";

Properties

Property	Attribute	Type	Default	Description
`formField`	`form-field`	`boolean`	`false`	Applies form field styles to the skeleton.
`button`	`button`	`boolean`	`false`	Applies button styles to the skeleton.
`chip`	`chip`	`boolean`	`false`	Applies chip styles to the skeleton.
`listItem`	`list-item`	`boolean`	`false`	Applies list item styles to the skeleton.
`text`	`text`	`boolean`	`false`	Applies text styles to the skeleton.
`avatar`	`avatar`	`boolean`	`false`	Applies avatar styles to the skeleton.
`stretch`	`stretch`	`boolean`	`false`	Applies stretch styles to the skeleton.

CSS Parts

Name	Description
`::part(root)`	The root element of the skeleton.

CSS Custom Properties

Name	Description
`--forge-skeleton-animation-duration`	The duration of the skeleton animation.
`--forge-skeleton-width`	The width of the skeleton.
`--forge-skeleton-height`	The height of the skeleton.
`--forge-skeleton-background`	The background color of the skeleton.
`--forge-skeleton-shape`	The shape of the skeleton.
`--forge-skeleton-margin`	The margin of the skeleton.
`--forge-skeleton-button-height`	The height of the button skeleton.
`--forge-skeleton-button-width`	The width of the button skeleton.
`--forge-skeleton-form-field-height`	The height of the form field skeleton.
`--forge-skeleton-form-field-width`	The width of the form field skeleton.
`--forge-skeleton-chip-height`	The height of the chip skeleton.
`--forge-skeleton-chip-width`	The width of the chip skeleton.
`--forge-skeleton-chip-shape`	The shape of the chip skeleton.
`--forge-skeleton-list-item-height`	The height of the list item skeleton.
`--forge-skeleton-list-item-margin`	The margin of the list item skeleton.
`--forge-skeleton-text-height`	The height of the text skeleton.
`--forge-skeleton-gradient-color`	The color of the gradient skeleton.
`--forge-skeleton-avatar-size`	The size of the avatar skeleton.
`--forge-skeleton-avatar-shape`	The shape of the avatar skeleton.

Hide from assistive technology

A skeleton is a purely visual loading placeholder — add aria-hidden="true" so screen readers skip over it instead of announcing meaningless placeholder content.