Loading

On this page

While a view loads, show a skeleton in the shape of what's coming, so the page doesn't jump when the content arrives. Use spinners only for small, short waits inside something that's already on screen.

Skeletons

Skeleton KPI tiles and a skeleton chart cardSkeleton KPI tiles and a skeleton chart card

Figure 1: Skeleton KPI tiles and a skeleton chart card

<div class="ph-stack" aria-busy="true" aria-label="Loading orders">
  <div class="ph-grid-3" aria-hidden="true">
    <div class="ph-card">
      <div class="ph-skeleton ph-skeleton-text" style="width: 40%"></div>
      <div class="ph-skeleton ph-skeleton-title" style="margin-top: 12px"></div>
    </div>
    ...
  </div>
  <article class="ph-card" aria-hidden="true">
    <div class="ph-skeleton ph-skeleton-title"></div>
    <div class="ph-skeleton ph-skeleton-block" style="height: 160px; margin-top: 16px"></div>
  </article>
</div>
ClassShape
.ph-skeletonThe shimmering placeholder. Combine it with one of the shapes below.
.ph-skeleton-textA line of text (12px tall)
.ph-skeleton-titleA title (20px tall, 40% wide)
.ph-skeleton-blockA block, 120px tall by default: set the height of what's coming (a 240px chart)

Mark the loading area aria-busy="true" with an aria-label, and hide the skeleton shapes themselves from screen readers.

Spinners and busy controls

Spinners, a busy button and an indeterminate progress barSpinners, a busy button and an indeterminate progress bar

Figure 2: A spinner, a large spinner, a busy button and an indeterminate progress bar

<span class="ph-spinner" role="status" aria-label="Loading"></span>
<span class="ph-spinner ph-spinner--lg" role="status" aria-label="Loading"></span>
<button type="button" class="ph-btn ph-btn--primary" aria-busy="true">Saving</button>
<div class="ph-progress ph-progress--indeterminate" role="progressbar" aria-label="Importing customers">
  <span class="ph-progress-fill"></span>
</div>
Class or attributeUse for
.ph-spinner (18px) / .ph-spinner--lg (32px)A short wait inside something already on screen
aria-busy="true" on a buttonSaving or sending: shows a spinner in the button and blocks clicks
.ph-progress--indeterminateA longer task with no known end, such as an import

With reduced motion turned on, skeletons stop shimmering and spinners stop turning.

React

Skeleton, SkeletonText, BlockSkeleton, CardSkeleton, TableSkeleton, StatGridSkeleton, ToolbarSkeleton, ListPageSkeleton and DashboardPageSkeleton from ph-app-kit-react draw skeletons for common shapes. Use one as the Suspense fallback for lazily loaded views, at the same height as the view.

Guidelines

  • Skeleton first, then the content, an empty state or an error. Never a blank screen.
  • Match the skeleton to the real layout: same tiles, same chart height, a few table rows.
  • During a refresh, keep showing the old data instead of going back to the skeleton.
  • Don't leave a spinner on its own for long. If it takes more than a few seconds, say what's happening.