Skeleton loader

v1.0.0

A skeleton is a graphical placeholder, reserving physical space in the page for content in cases where a service or action may be slow to resolve. A skeleton can be considered as an alternative to the progress spinner in many situations.

  • Skin
  • Marko
  • React
Stylized artwork of a skeleton loader.

Considerations

Lightweight

Skeleton states are simple tools that portray that content is still being loaded—helping reduce user uncertainty.

Structured

Skeletons provide visual hierarchy and suggest the content they are meant to represent whenever possible.

Quick

Skeletons should only appear for a few seconds when needed and disappear when content populates a page.

Anatomy

Skeletons are built using shapes as the base layer and stacked with a shimmer gradient to create the loading effect on native screens. Please note the shimmer is omitted on larger web screens.

Spec for a skeleton loader. Number 1 points to the shapes that make up the skeleton. Number 2 points to the shimmer gradient.
  1. Shape
  2. Shimmer

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. View helpful skeleton examples in the Skin library.

Usage guidance

When to use

  • Skeleton loaders on initial page render should be used as a last resort and not built as an integral part of the design
  • If UI elements need to be loaded
  • If visual layout/format of the content being loaded is mostly known ahead of time to reduce the probability of layout shift
  • If the majority of the page will be taking time to load

When to consider something else

  • If the visual layout/format of the content being loaded is unknown
  • If you need to indicate processing or that a change will occur on the page
  • If content can be pre-loaded or optimized in another way, don’t default to skeleton loaders because they’re easy to leverage

Properties

Shape

Skeleton loading experiences are built using simple shapes found within our common components.

Various shapes with labels: A single big square is labeled ‘Image’, a square with a rounded corner radius is labeled ‘image’ with two rectangular lines below labeled ‘text’, a small circle is labeled ‘avatar’, a long rectangle with a 100% rounded corner radius is labeled ‘button’, and a long rectangle with an 8px rounded corner radius is labeled ‘form’.

Radius

The radii across shapes vary depending on the component:

  • Images are 8 or 16px and follow our image sizing guidance
  • Text blocks are 4px
  • Buttons are fully rounded
  • Forms are 8px
  • Full-width images bleed on all edges and have no radius
Various rectangles with different corner radii are labeled: An inset image has an 8 or 16px corner radius, text has a 4px corner radius, button has a 100% corner radius, form has an 8px corner radius, a full width image has 0px corner radius.

Default color

Skeletons work across both light and dark modes. Learn more about the available Loading color tokens.

A skeleton is shown in light and dark mode. For light and dark mode, the tokens loading.fill and loading.shimmer are used.

On Secondary color

Skeletons also work on our background secondary color.

A skeleton is shown in light and dark mode with a secondary background color. For light and dark mode, the tokens color.loading.fillOnSecondary and color.gradient.loading.shimmerOnSecondary are used.

Generative AI color

Colored gradient skeletons are used when introducing AI features and generated content. Learn more about how we treat generative AI in the Generative AI foundation. These colored gradients are only to be used for generative AI content.

Two mobile examples showing subtle gradients being used as loading states. The first shows the background of an assistant module using the subtle blue gradient. The second shows a skeleton loader using the subtle purple gradient.

Building skeletons

Skeletons are structural elements that represent the visual hierarchy of a page. They should be used as simplified placeholders for content versus 1:1 replacements to create simple loading experiences.

Introduction

Keep in mind that a full page skeleton may not be required or used on page load. In most cases titles, imagery, and other content is able to be pre-loaded. Skeletons should only be used for content that is not yet ready. Don’t force a skeleton when it isn’t needed or if it will make the loading experience uncomfortable.

A lounge chair eBay listing is shown on mobile and desktop. The listing displays the product image and item title, and skeleton loaders are placed in areas that hold additional information.

Example

To visually portray how skeletons will look on a page, here is an example of an overarching hierarchy of content. Notice the common components in use such as images, text groups, buttons, and forms that build the overall structure. Detailed elements like program badges, smaller lines of text and icons should not be represented by skeletons. To view a variety of skeleton examples on web, visit the Skin library.

A lounge chair eBay listing is shown on mobile and desktop. Pink blocks overlay the areas in the listing that would require a skeleton loader: main image, product images, item title, seller information, condition, action buttons.
eBay listing screens are shown on desktop and mobile with skeleton loaders applied.

Best practices

Styling

Do use skeletons in gray when not representing generative AI. Generative AI uses approved color gradients.

A grey skeleton loader.

Don’t manually change skeletons to arbitrary colors.

A blue skeleton loader.

Do use the radius found within the components.

A skeleton loader with the correct corner radii applied (16px for inset image, 4px for text).

Don’t adjust the radius of the skeleton components.

A skeleton loader with the incorrect corner radii applied (40px for inset image, 8px for text).

Do use available skeleton components.

Text skeleton component.

Don’t turn other elements like icons into skeletons or make your own skeleton components.

An icon converted into a skeleton loader.

Construction

Do use skeleton layouts that are simplified and hint at the visual hierarchy of a page.

A simplified skeleton loader sits on a view item page.

Don’t replace elements 1:1 on a page as a skeleton layout. Complex skeletons can be distracting and provide a poor experience.

A complex skeleton loader sits on a view item page.

Do use skeletons for elements inside a modal if needed.

Skeleton loaders sit inside of a modal.

Don’t represent a modal as a skeleton state.

An empty modal.

Do use skeletons for common components like images, text, avatars, buttons and forms.

A skeleton loader sits in place of text and avatars on the eBay app.

Don’t use skeletons for tool tips, alert notices, snackbars, or navigation buttons.

A skeleton loader sits inside of a snackbar on the eBay app.

Behavior

Do use skeleton loading by itself.

A page of skeleton loaders sits on an eBay mobile page.

Don’t combine skeleton loading with other loading types.

A loading spinner sits on top of skeleton loaders on an eBay mobile page.

Do animate shimmer effects in the same direction at the same time.

Video description: A shimmer animation on a skeleton loader timed correctly in the same direction.

Don’t offset skeleton shimmer animations.

Video description: A shimmer animation on a skeleton loader animating at different times and at different directions.

Do use the shimmer animation on native screens.

A shimmer animation is shown on skeleton loaders on the eBay app.

Don’t use the shimmer animation on larger html screens unless the load is taking longer than 2.5 seconds.

A shimmer animation is shown on skeleton loaders on an eBay desktop page.

Specs

Item tile skeleton loader is shown with specs highlighted. Padding between the image and first line of type is 12px, padding between the type block is 8px, the height of the type is 16px.

Item tile

A large and small type block skeleton loaders are shown with specs highlighted. A single larger type block height is 24px, the smaller is 16px. The padding between larger and smaller type blocks is 8px.

Type

A large and small type block skeleton loaders are shown with specs highlighted. Padding to the right of the type blocks is 24px. The second type line in a type block is 56px shorter in width than the first longer type line in the block.

Type block

Form, button, and avatar skeleton loaders are shown with specs highlighted. The form skeleton loader is 48px in height. The button skeleton loaders range in three sizes: 48px, 40px, and 32px in height. The icon skeleton loader is 48px in height.

Form, button, and avatar

Change log

VersionDateNotes
1.1.0
Nov, 2024
  • Updated overall guidance
  • Updated to eBay Evo
1.1.0
Sep, 2023
  • Added “default/40px” button to the skeleton button component
1.0.0
Mar, 2023
  • Skeleton loader documentation created