Skeleton

Skeleton vs Loader #

Use Skeleton when:

• Content is expected to take more than a few hundred milliseconds to load on average
• You want to show the approximate layout and structure of content being loaded
• Loading complex lists, cards, or detailed content where users benefit from seeing the expected layout
• You need to maintain visual hierarchy during loading states

Use Loader when:

• You need a simple, generic loading indicator
• Loading time is short or indeterminate
• You want to indicate that a process is running without showing layout structure
• You need a compact loading indicator for buttons, small components, or overlays

Usage #

Variants #

Default #

<dt-skeleton :animate="false" aria-label="Loading" />

Animation #

<dt-skeleton aria-label="Loading" />

Custom #

To customize a non-animating Skeleton background color modify the --placeholder-from-color variable with an inline style.

<dt-skeleton
  :animate="false"
  :text-option="{
    style: `--placeholder-from-color: var(--dt-color-blue-400)`,
  }"
  aria-label="Loading"
/>

Customize an animating Skeleton by modifying the --placeholder-from-color and --placeholder-to-color variables with an inline style.

<dt-skeleton
  :text-option="{
    style: `--placeholder-from-color: var(--dt-color-blue-400); --placeholder-to-color: var(--dt-color-blue-200);`,
  }"
  aria-label="Loading"
/>

Shapes #

Avatar #

Default sizes match the avatar size. Size is customizable when needed.

<dt-skeleton :shape-option="{ shape: `circle`, size: `sm` }" :animate="false" />
<dt-skeleton :shape-option="{ shape: `circle` }" :animate="false" />
<dt-skeleton :shape-option="{ shape: `circle`, size: `lg` }" :animate="false" />

Image / Icon #

<dt-skeleton :shape-option="{ shape: `square`, size: `sm` }" :animate="false" />
<dt-skeleton :shape-option="{ shape: `square` }" :animate="false" />
<dt-skeleton :shape-option="{ shape: `square`, size: `lg` }" :animate="false" />

Headings #

<dt-skeleton :text-option="{ type: `heading`, headingHeight: `sm`, width: `160px` }" :animate="false" />
<dt-skeleton :text-option="{ type: `heading`, width: `240px` }" :animate="false" />
<dt-skeleton :text-option="{ type: `heading`, headingHeight: `lg`, width: `320px` }" :animate="false" />

Prefabricated Combinations #

Paragraphs #

<dt-skeleton
  :paragraph-option="{
    rows: 5,
    randomWidth: true,
  }"
  :animate="false"
/>

Avatar + Name #

<dt-skeleton
  :list-item-option="{
    shapeSize: `sm`,
    paragraphs: {
      rows: 1,
    },
  }"
/>

Icon + Text #

<dt-skeleton
  :list-item-option="{
    shapeSize: `2rem`,
    shape: `square`,
    paragraphs: {
      rows: 1,
    },
  }"
/>

Messages / Transcript / Comment #

<dt-skeleton
  :list-item-option="{
    shapeSize: `3.6rem`,
    paragraphs: {
      rows: 4,
      width: [
        `120px`, `311px`, `371px`, `279px`,
      ],
    },
  }"
/>

Accessibility #

For sighted users, they are able to see that there is loading content and no other action is needed until loading completes. Likewise, there is nothing that needs to be added for keyboard users. For users who rely on assistive technology, skeleton’s visual representation of a loading state won’t be accessible without additional labeling.

It's role="status" on the skeleton component, keep in mind, that:

• The aria live region role of status has an implicit aria-live value of polite, which allows a user to be notified via AT (such as a screen reader) when status messages are added. The role of status also has a default aria-atomic value of true, so that updates to the container marked with a role of status will result in the AT presenting the entire contents of the container to the user, including any author-defined labels (or additional nested elements).

• aria-busy state indicates an element is being modified and that assistive technologies may want to wait until the changes are complete before informing the user about the update. When multiple parts of a live region need to be loaded before changes are announced to the user, set aria-busy="true" until loading is complete. Then set to aria-busy="false". This prevents assistive technologies from announcing changes before updates are done.

• If you need fully accessible skeleton and loading content, probably you will want to add aria-live="polite" and aria-busy="false" to corresponding loaded html element content.

<dt-skeleton
  v-if="loading"
  :aria-label="$i18n('Loading')"
/>
<p
  v-else
  aria-live="polite"
  aria-busy="false"
>
  Loaded content.
</p>

References #

• Aria-busy, Status role, ARIA22, a11y support status_role
• Carbon DS Loading pattern, Skeleton screens
• Short note on being busy, More Accessible Skeletons

Vue API #

Props