@ebay/skin/skeleton BETA

Cumulative Layout Shift (CLS)

It is the developer's responsibility to ensure the CLS metric of a page is not negatively impacted by the introduction of a skeleton placeholder; a poor CLS score will occur whenever content shifts unexpectedly . Unexpected movement of page content usually happens because resources are loaded asynchronously or DOM elements get dynamically added to the page above existing content. Skeletons can help mask these problems if they reserve the correct amount of physical space, but can compound the problem when they do not.

The Skeleton Use Guide illustrates various techniques for implementing skeletons across some common loading scenarios.

Skeleton Types

SkeletonDefaultOn-SecondaryPurpleGreenBlue
Avatar
Button
Textbox
Image
Text

On large screens, skeleton loaders use a solid fill for background color; on small screens, a shimmer is applied.

The color can be changed to purple, green or blue by applying the appropriate modifier, e.g. skeleton--green . View the composite skeletons examples for further details.

Avatar Skeleton

Use the skeleton__avatar class to create a skeleton placeholder for an avatar.

<div class="skeleton" role="img" aria-label="loading">
  <div class="skeleton__avatar" />
</div>

Button Skeleton

Use the skeleton__button class to create a skeleton placeholder for the default button shape.

<div class="skeleton" role="img" aria-label="loading" style="width: 200px">
  <div class="skeleton__button" />
</div>

Use the small modifier to match the shape of a small button.

<div class="skeleton" role="img" aria-label="loading" style="width: 200px">
  <div class="skeleton__button skeleton__button--small" />
</div>

Use the large modifier to match the shape of a large button.

<div class="skeleton" role="img" aria-label="loading" style="width: 200px">
  <div class="skeleton__button skeleton__button--large" />
</div>

Textbox Skeleton

Use the skeleton__textbox class to create a skeleton placeholder for a textbox.

<div class="skeleton" role="img" aria-label="loading" style="width: 200px">
  <div class="skeleton__textbox" />
</div>

Image Skeleton

Use the skeleton__image class to create a skeleton placeholder for an image.

<div class="skeleton" role="img" aria-label="loading">
  <div class="skeleton__image" style="height: 50px; width: 50px" />
</div>

Notice that the height and width must be set on the skeleton__image element.

<div class="skeleton" role="img" aria-label="loading">
  <div class="skeleton__image" style="height: 200px; width: 200px" />
</div>

Text Block Skeleton

Use the skeleton__text class to create a skeleton for a single block of text.

<div class="skeleton" role="img" aria-label="loading" style="width: 200px">
  <div class="skeleton__text skeleton__text--small" />
</div>

Use the skeleton__text--large modifier to match the shape of a large block of text.

<div class="skeleton" role="img" aria-label="loading" style="width: 200px">
  <div class="skeleton__text skeleton__text--large" />
</div>

Use the skeleton__text--multiline mofifier to create a skeleton for two lines of text.

<div class="skeleton" role="img" aria-label="loading" style="width: 200px">
  <div class="skeleton__text skeleton__text--multiline" />
</div>

Composite Skeleton

Combinations of skeletons can form a custom placeholder for more complex content, such as a typical eCommerce item tile in the example below.

<div
  class="skeleton skeleton--purple"
  role="img"
  aria-label="loading"
  style="width: 225px"
>
  <div class="skeleton__image" style="width: 225px; height: 225px" />
  <div class="skeleton__text skeleton__text--multiline" />
</div>

Here is a skeleton for a compact user profile. Notice that a div tag can be replaced with a span tag for inline-block layout of elements.

<div class="skeleton skeleton--blue" role="img" aria-label="loading">
  <span class="skeleton__avatar" />
  <span
    class="skeleton__text skeleton__text--multiline"
    style="width: 200px; vertical-align: top"
  />
</div>

Skeleton Animation EXPERIMENTAL

The skeleton loader uses view-transition animation to swap between the skeleton and the loaded content. This is an experimental feature and may not be supported in all browsers.

In order to use view-transition animation, the skeleton must have a view-transition-name style attribute set. The value of the attribute must be unique for each skeleton on the page. For this you can use skeleton-transition-1 and skeleton-transition-2 etc view transition names. These names should correspond to the loaded content view transition names so that they can transition properly.

We have defined skeleton-transition-* so that you can use any arbitray name after skeleton-transition-. Just make sure that the names are unique and do not conflict with other view transition names on the page. Also verify that the view-transition-name set on the skeleton matches the view-transition-name set on the loaded content.

Reminder: when swapping between the skeleton and the loaded content, use document.startViewTransition() to start the view transition.

<button type="button" class="btn skeleton-trigger">Load content</button>
<div class="skeleton" role="img" aria-label="loading" style="display: flex">
  <span
    id="skeleton-transition-0"
    class="skeleton__image"
    style="
      height: 200px;
      width: 200px;
      view-transition-name: skeleton-transition-0;
    "
  />
  <span
    id="skeleton-transition-1"
    class="skeleton__image"
    style="
      height: 200px;
      width: 200px;
      view-transition-name: skeleton-transition-1;
    "
  />
  <span
    id="skeleton-transition-2"
    class="skeleton__image"
    style="
      height: 200px;
      width: 200px;
      view-transition-name: skeleton-transition-2;
    "
  />
</div>

Skeleton Variables EXPERIMENTAL

The following custom properties (aka CSS Variables) are available for component-level overrides and other general theming purposes.

  • --skeleton-background
Signal ComponentSnackbar Dialog Component