VERIFICATION-0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
Loading contentSkeleton
<forma-skeleton>
Low-information loading placeholder with explicit busy semantics; its shimmer is a named cadence that runs only while aria-busy is true and stops for reduced motion.
- Authoring tag
<forma-skeleton>- Category
- Feedback and status
- Behavior owner
- Application state
- Canonical source
patterns/skeleton.html
Purpose
A skeleton holds the approximate shape of content that is still loading, so the layout does not jump when the content arrives. Forma renders a bordered region of neutral bars; title and short modifiers vary their length. The region carries aria-busy="true" and a text label while loading, and the shimmer runs only while that attribute is true. The application replaces the skeleton with real content (or an empty, error or unknown state) when it has an answer.
Use when
- A card, panel or list is loading and its approximate layout is known.
- Content arrives in a few hundred milliseconds to a few seconds and a layout shift would be disruptive.
- Several regions load independently and each needs its own placeholder.
Avoid when
- The wait is for an action the user just took, such as saving: use Spinner with a label naming the action.
- The amount of work is known: use Progress bar.
- Loading has finished with no data: use Empty state. A skeleton must never stand in for empty or failed content.
Behavior to know
- Bars carry no information; the region's label is the only content.
- The shimmer uses the shared cadence
--forma-motion-cadence-period(1600ms), linear, identical for every line. - Setting
aria-busy="false"stops the shimmer, and a static skeleton remains a valid presentation.
Basic example
The smallest correct markup: the canonical pattern from patterns/skeleton.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal skeleton
Rendered from the canonical pattern file.
<forma-skeleton class="forma-component-tag">
<section class="forma-skeleton" aria-busy="true" aria-label="Loading content">
<span class="forma-visually-hidden">Loading content</span>
<div class="forma-skeleton__line forma-skeleton__line--title"></div>
<div class="forma-skeleton__line"></div>
<div class="forma-skeleton__line"></div>
<div class="forma-skeleton__line forma-skeleton__line--short"></div>
</section>
</forma-skeleton>
Click or tap the code once to select all of it, then copy.
Examples
Panel with a known heading
The panel heading is already known, so it is rendered as real text and names the busy region with aria-labelledby. Only the body is a placeholder, and the visually hidden text says what is loading.
Recent activity
Loading recent activity<forma-skeleton class="forma-component-tag">
<section class="forma-skeleton" aria-busy="true" aria-labelledby="skeleton-labelled-panel-title">
<h3 id="skeleton-labelled-panel-title">Recent activity</h3>
<span class="forma-visually-hidden">Loading recent activity</span>
<div class="forma-skeleton__line"></div>
<div class="forma-skeleton__line forma-skeleton__line--short"></div>
<div class="forma-skeleton__line"></div>
<div class="forma-skeleton__line forma-skeleton__line--short"></div>
</section>
</forma-skeleton>
Click or tap the code once to select all of it, then copy.
Card grid loading
Three skeleton cards in a responsive Grid while a dashboard loads. Each card is its own busy region, so the application can replace them one by one as data arrives.
<forma-skeleton class="forma-component-tag">
<div class="forma-grid">
<section class="forma-skeleton" aria-busy="true" aria-label="Loading revenue">
<div class="forma-skeleton__line forma-skeleton__line--title"></div>
<div class="forma-skeleton__line forma-skeleton__line--short"></div>
</section>
<section class="forma-skeleton" aria-busy="true" aria-label="Loading open invoices">
<div class="forma-skeleton__line forma-skeleton__line--title"></div>
<div class="forma-skeleton__line forma-skeleton__line--short"></div>
</section>
<section class="forma-skeleton" aria-busy="true" aria-label="Loading overdue balance">
<div class="forma-skeleton__line forma-skeleton__line--title"></div>
<div class="forma-skeleton__line forma-skeleton__line--short"></div>
</section>
</div>
</forma-skeleton>
Click or tap the code once to select all of it, then copy.
Stalled load with explanation
Loading is taking longer than expected. The application sets aria-busy="false" so the shimmer stops, and shows a plain text note with a retry action instead of letting the placeholder shimmer indefinitely.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
Customer history
This is taking longer than usual. The request is still open.
<forma-skeleton class="forma-component-tag">
<section class="forma-skeleton" aria-busy="false" aria-labelledby="skeleton-stalled-load-title">
<h3 id="skeleton-stalled-load-title">Customer history</h3>
<div class="forma-skeleton__line"></div>
<div class="forma-skeleton__line forma-skeleton__line--short"></div>
<p>This is taking longer than usual. The request is still open.</p>
<button type="button">Try again</button>
</section>
</forma-skeleton>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Mobile message list
A list placeholder at phone width.
What changes at narrow widths
- Lines are percentage widths (100%, 72% short, 55% title), so they scale with the screen instead of overflowing.
- The region fills the container width; no horizontal scrolling at 320px.
- Keep the skeleton roughly the height of the expected content, so arriving content does not push the rest of the page down on a small screen.
- There are no touch targets inside a skeleton; any action is added only when loading stalls or fails.
<forma-skeleton class="forma-component-tag">
<section class="forma-skeleton" aria-busy="true" aria-label="Loading messages">
<span class="forma-visually-hidden">Loading messages</span>
<div class="forma-skeleton__line forma-skeleton__line--title"></div>
<div class="forma-skeleton__line"></div>
<div class="forma-skeleton__line forma-skeleton__line--short"></div>
<div class="forma-skeleton__line forma-skeleton__line--title"></div>
<div class="forma-skeleton__line"></div>
<div class="forma-skeleton__line forma-skeleton__line--short"></div>
</section>
</forma-skeleton>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
aria-busy | section.forma-skeleton | true | false | — | Marks the region as loading. The shimmer runs only while it is true. |
aria-label | section.forma-skeleton | string | — | Names the busy region when no visible heading exists ("Loading content"). |
aria-labelledby | section.forma-skeleton | id of a visible heading | — | Names the region from a real heading when the heading is already known. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-skeleton | Block class | — | Root region: a bordered grid of placeholder lines. |
.forma-skeleton__line | Element class | — | A full-width 0.9rem neutral bar with a shimmer gradient. |
.forma-skeleton__line--short | Modifier class | — | 72% wide, standing in for the last line of a paragraph. |
.forma-skeleton__line--title | Modifier class | — | Taller (1.4rem) and 55% wide, standing in for a heading. |
[aria-busy] | Attribute hook | "true" | The shimmer selector: .forma-skeleton[aria-busy="true"] animates its lines; any other value leaves them static. |
| Keys | Result |
|---|---|
| — | A skeleton has no focusable content. Do not put interactive placeholders inside it. |
| Event | Description |
|---|---|
— | None. The application replaces the skeleton or changes aria-busy. |
Form behavior
Not a form control.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Loading | aria-busy="true" | Lines shimmer at the shared cadence. |
| Static | aria-busy="false" or absent | Lines stay in place without motion. Use when loading has stalled, or replace the skeleton entirely. |
| Reduced motion | prefers-reduced-motion: reduce | The shimmer is removed; the busy semantics and label remain. |
Accessibility
Forma provides
- Ties the shimmer to
aria-busy, so the visual activity and the exposed busy state cannot disagree. - Stops the shimmer under reduced motion.
- Keeps placeholder bars free of text, so nothing meaningless is announced.
Your application supplies
- Label the region with
aria-label,aria-labelledby, or visually hidden text that says what is loading. Avoid giving it the same text twice, which some screen readers read twice. - Replace the skeleton with real content, an Empty state, or an error; never leave it indefinitely.
- Move focus only if the user was focused inside the region being replaced.
Responsive behavior
Motion
- While
aria-busy="true", each line's gradient moves across it once per--forma-motion-cadence-period(1600ms), linear and infinite: constant-velocity cadence with no bounce. - Every line shares the same period, so no part of the placeholder appears faster or more important.
- The shimmer stops as soon as
aria-busyis no longer true. - Under
prefers-reduced-motion: reducethe animation is removed and the lines are static.
Usage guidance
Do
- Approximate the real layout: a title line, a few body lines, a short last line.
- Replace skeletons as each piece of content arrives rather than waiting for everything.
Avoid
- Showing a skeleton for data that has already failed to load.
- Skeletons for waits under a few hundred milliseconds, which only add flicker.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.