Primitives Feedback
Skeleton
Placeholders shaped like the content that is loading, so the layout holds still until it arrives. CSS only.
Markdown version of this page, for assistants (Markdown for AI)
On this page
Loading the team
Code
<script lang="ts">
// Nothing to import at runtime: the placeholders are CSS. The stylesheets are optional.
import '@svelte-lean/styles/progress.css';
import '@svelte-lean/styles/skeleton.css';
</script>
<!-- The loading state in words, outside the busy region. -->
<p class="status" role="status">
<progress data-slean="progress" data-variant="circular" data-size="small" aria-hidden="true"></progress>
Loading the team
</p>
<div class="card" aria-busy="true">
<div class="person">
<span data-slean="skeleton" data-variant="circular" aria-hidden="true"></span>
<div class="lines">
<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
</div>
</div>
<span data-slean="skeleton" data-variant="rounded" aria-hidden="true"></span>
<div class="lines">
<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
</div>
</div>
<style>
.status {
display: flex;
align-items: center;
gap: var(--slean-space-2);
margin-block: 0 var(--slean-space-3);
}
.card {
display: grid;
gap: var(--slean-space-4);
max-inline-size: 24rem;
}
.person {
display: flex;
align-items: center;
gap: var(--slean-space-3);
}
.lines {
flex: 1;
}
</style>Examples
Swapping in the content
Design lead, Istanbul
Works on the design system and the documentation site. Reviews every new primitive.
Code
<script lang="ts">
import '@svelte-lean/styles/button.css';
import '@svelte-lean/styles/progress.css';
import '@svelte-lean/styles/skeleton.css';
let loading = $state(false);
function reload() {
loading = true;
// Stands in for a request.
setTimeout(() => (loading = false), 1800);
}
</script>
<div class="toolbar">
<button type="button" data-slean="button" data-variant="outlined" data-color="neutral" onclick={reload}>Reload</button>
<!-- In the page from the start and empty: the text written into it is read. -->
<p class="status" role="status">
{#if loading}
<progress data-slean="progress" data-variant="circular" data-size="small" aria-hidden="true"></progress>
Loading the profile
{/if}
</p>
</div>
<div class="card" aria-busy={loading}>
{#if loading}
<div class="person">
<span data-slean="skeleton" data-variant="circular" aria-hidden="true"></span>
<div class="lines">
<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
</div>
</div>
<div class="lines">
<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
</div>
{:else}
<div class="person">
<span class="avatar" aria-hidden="true">AO</span>
<div class="lines">
<strong>Amara Okafor</strong>
<p>Design lead, Istanbul</p>
</div>
</div>
<p>Works on the design system and the documentation site. Reviews every new primitive.</p>
{/if}
</div>
<style>
.toolbar {
display: flex;
align-items: center;
gap: var(--slean-space-3);
margin-block-end: var(--slean-space-4);
}
.card {
display: grid;
gap: var(--slean-space-4);
max-inline-size: 24rem;
}
.person {
display: flex;
align-items: center;
gap: var(--slean-space-3);
}
.lines {
flex: 1;
}
.card p {
margin: 0;
}
.lines p {
color: var(--slean-fg-muted);
font-size: var(--slean-text-sm);
}
.avatar {
display: grid;
place-items: center;
inline-size: 2.5rem;
block-size: 2.5rem;
border-radius: var(--slean-radius-full);
background: var(--slean-muted);
font-size: var(--slean-text-sm);
font-weight: var(--slean-font-weight-medium);
}
</style>A list
Code
<script lang="ts">
import '@svelte-lean/styles/skeleton.css';
</script>
<ul class="rows" aria-busy="true" aria-label="Messages">
{#each [1, 2, 3] as row (row)}
<li>
<span data-slean="skeleton" data-variant="circular" data-size="small" aria-hidden="true"></span>
<div class="lines">
<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
</div>
</li>
{/each}
</ul>
<style>
.rows {
display: grid;
gap: var(--slean-space-4);
max-inline-size: 24rem;
margin: 0;
padding: 0;
list-style: none;
}
.rows li {
display: flex;
align-items: center;
gap: var(--slean-space-3);
}
.lines {
flex: 1;
}
</style>Looks
Code
<script lang="ts">
import '@svelte-lean/styles/skeleton.css';
</script>
<div class="shapes" aria-hidden="true">
<div class="circles">
<span data-slean="skeleton" data-variant="circular" data-size="small"></span>
<span data-slean="skeleton" data-variant="circular"></span>
<span data-slean="skeleton" data-variant="circular" data-size="large"></span>
</div>
<div>
<span data-slean="skeleton" data-variant="text"></span>
<span data-slean="skeleton" data-variant="text"></span>
</div>
<!-- rectangular and rounded take their size from the application's CSS. -->
<div class="circles">
<span data-slean="skeleton" data-variant="rectangular" class="thumbnail"></span>
<span data-slean="skeleton" data-variant="rounded" class="thumbnail"></span>
</div>
</div>
<style>
.shapes {
display: grid;
gap: var(--slean-space-4);
max-inline-size: 24rem;
}
.circles {
display: flex;
align-items: center;
gap: var(--slean-space-3);
}
.thumbnail {
inline-size: 8rem;
block-size: 5rem;
}
</style>Usage
Plain markup with a stylesheet: install @svelte-lean/styles. No JavaScript runs.
npm install @svelte-lean/stylespnpm add @svelte-lean/stylesyarn add @svelte-lean/stylesbun add @svelte-lean/stylesimport '@svelte-lean/styles/skeleton.css';Render the placeholders inside the element the content will fill, give it aria-busy="true", and replace them with the content in one update.
Say that the region is loading in text outside the busy region, in a status region that is in the page before the wait begins: a screen reader may skip the content of a busy region.
Anatomy
| Part | Element | data-slean-part | Required | Notes |
|---|---|---|---|---|
| root | <span data-slean="skeleton" aria-hidden="true"> | – | yes | data-variant="text|rectangular|rounded|circular"; data-size="small|large" on a circular one. |
| busy region | <div aria-busy="true"> | – | yes | The element the content will fill. The loading text stays outside it. |
| status | <p role="status"> | – | yes | Says what is loading, in words, outside the busy region; in the page before the wait begins. A small circular progress beside the text may be aria-hidden. |
Keyboard
| Key | When | Result |
|---|---|---|
| Tab | anywhere | Skips the placeholders: they are not focusable |
Styling
skeleton.css gives each shape the muted tint and a band of the hover tint in a background three times the box’s width. A keyframe animation moves the band across; at rest, and under reduced motion, the band sits outside the box. The last of several text lines is shorter. Under forced colors the shapes become outlines. The tokens it reads:
| Token | Default (light) | Applies to |
|---|---|---|
--slean-radius-sm | calc(var(--slean-radius) * 0.6) | border-radius |
--slean-muted | var(--slean-neutral-3) | background-color |
--slean-muted-hover | var(--slean-neutral-4) | background-image |
--slean-duration-slow | 240ms | animation |
--slean-control-height-md | 2.25rem | inline-size, block-size |
--slean-control-height-sm | 2rem | inline-size, block-size |
--slean-radius-md | var(--slean-radius) | border-radius |
State selectors the stylesheet targets, all from the platform or ARIA: :dir(rtl), :first-child, :last-child.
Variant attributes: data-variant (text, circular, rectangular, rounded); data-size (small, large).
Controlled integration
The application owns the loading state. With {#await} the placeholders are the pending branch and the content the resolved one, so they are replaced in one update.
<script lang="ts">
import Team from './Team.svelte';
const team = fetch('/api/team').then((response) => response.json());
</script>
{#await team}
<p class="status" role="status">
<progress data-slean="progress" data-variant="circular" data-size="small" aria-hidden="true"></progress>
Loading the team
</p>
<div aria-busy="true">
<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
</div>
{:then members}
<div aria-busy="false"><Team {members} /></div>
{/await}Under the hood
Runtime and size
- Tier
- 0 · Native
- Behavior JS
- 0 B brotli · 0 B gzip ·
fixtures/· methodresults.json (native-only) - Platform features
aria-hidden,aria-busy,prefers-reduced-motion,:dir(rtl)- Shared listeners
- none
- Per-instance listeners
- none
- Lazy state
- none
- Native base
aria-hidden placeholders in an aria-busy region
Tier 0: the skeleton has no behavior module, the Vite plugin maps skeleton to no module, and the page ships no Svelte Lean JavaScript for it. The shimmer is a CSS animation.
Why this implementation
A skeleton keeps the layout in place while content loads, so the page does not jump when it arrives. It is a visual device: an empty shape means nothing to a screen reader, and a list of empty shapes read aloud is noise.
Svelte Lean ships the shapes as CSS, hidden with aria-hidden, and a contract that puts the meaning elsewhere: aria-busy on the region that will hold the content, and the loading state in text outside that region.
The browser owns
- removing the placeholders from the accessibility tree (aria-hidden)
- telling assistive technology that the region is updating (aria-busy)
- running the CSS animation, and reporting the reduced motion preference
Svelte Lean owns
- skeleton.css: the text, rectangular, rounded and circular shapes, the shorter last line, the sizes
- the shimmer, flat at rest and under reduced motion
- the contract
- documentation
Accessibility
- Each placeholder is empty and
aria-hidden="true". - The region that is loading carries
aria-busy="true"until the content is in place. - The loading state is said in text outside the busy region.
- Under reduced motion the duration tokens are zero and the placeholders are a flat tint.
Platform features
| Feature | Baseline | Outside the target |
|---|---|---|
aria-hidden, aria-busy | ARIA 1.1 states, exposed by every current browser | Not applicable; screen readers differ in their use of aria-busy |
:dir() | Baseline 2023 | The shimmer moves from left to right under RTL as well |
Without JavaScript
The placeholders are CSS and render; they stay until the application’s script replaces them. A page whose content arrives only through the script needs a server-rendered alternative.
Server rendering and hydration
Render the placeholders on the server when the content is fetched in the browser. Content the server renders needs no skeleton.
Nothing is attached. The placeholders rendered on the server stay until the application replaces them.
Compatibility
aria-hidden and aria-busy are ARIA 1.1 states, exposed by every current browser; screen readers differ in what they do with aria-busy. :dir() (Baseline 2023) reverses the shimmer under RTL.
Tests and source
apps/playground/tests/primitives/feedback-navigation.spec.tsPlaywright: roles, names and states in the accessibility tree, keyboard, RTL, reduced motion, axepackages/styles/testsstatic checks of the stylesheet (layers, tokens, specificity, dark parity)
packages/primitives/src/skeleton/contract.mdthe contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behaviorpackages/primitives/src/skeleton/contract.tstyped constants: name, tier, base, parts, options, eventspackages/styles/css/skeleton.cssthe optional stylesheet