Loading placeholders
Shapes where the content will be, so nothing jumps when it arrives. Pictures and videos get a frame of their own.
When to use it
- A page or a list fetches its content after it opens: placeholders where the content will be.
- A picture or video arrives after the page: a media frame that holds its space.
Use something else when:
- Something the person started is under way and you know how far: a progress bar.
- It takes under a fifth of a second: nothing. Placeholders wait that long before they show.
How it works: media frames
A picture or video inside .sn-media keeps its space while it loads. The frame sweeps like the other placeholders and shows a faint picture or play mark, then the picture fades in. Its description (alt text) never shows as stray words while it waits. If it can't load, the sweep stops and the mark stays, so the page never shows a broken picture.


Show code
<!-- A picture: the placeholder in its space until it arrives, then it fades in -->
<div class="sn-media" style="--sn-media-ratio:4 / 3">
<img src="…" alt="…" loading="lazy">
</div>
<!-- A video: until it has a frame (or its poster) to show -->
<div class="sn-media"><video poster="…" muted playsinline>…</video></div>
<!-- Shown whole, at its own shape, once it has loaded -->
<div class="sn-media sn-media--whole"><img src="…" alt="…"></div> - Shape:
--sn-media-ratio(16 / 9 by default). The picture fills it (object-fit: cover). Add.sn-media--wholeto hold that shape only while it loads and then show the picture at its own shape. - Script:
lib/media-frame.js. Base runswatchMedia()on every page, and it follows frames added later by script (Somnia CMS builds its pages that way), including pictures whose address is set afterwards.markMediaFailed(frame)is for a page that already knows a picture can't be shown. - A photo on its own:
img.sn-photogets the same sweep inside its own box, for photos already sized by their page (the main picture of articles and case studies). - Only for opaque photos and video. Logos, icons and anything with transparent parts would show the grey through.
Page placeholders
While a page fetches its content, Skeleton.astro (or lib/skeleton.js by script) shows soft shapes in its place: cards, rows, fields or editor. They fade in after 0.2 seconds, so quick loads never flicker.
Show code
<Skeleton kind="cards" count={3} label="Loading example cards" /> Accessibility
What it does for you
- A placeholder says what is loading once, as a status. The shapes themselves are hidden from screen readers.
- A picture in a media frame is in the page while it loads, so its description is read as usual. Its description never shows as stray words while it waits.
- A picture that can’t load keeps its place and a mark, never a broken-picture icon.
- Nothing in a placeholder is a stop for the keyboard.
- With reduced motion there is no sweep and no fade.
- Placeholders wait a fifth of a second before showing, so a quick load never flickers.
What you need to do
- A label that says what is loading: "Loading the report", not "Loading".
- Alt text on the picture in a frame, as on any picture.
- When the content arrives, put the focus somewhere sensible if the person was waiting on it.
Keyboard
| Key | What it does |
|---|---|
| Tab | Nothing: placeholders are not controls. |
What a screen reader is told
- The placeholder’s label, once: "Loading example cards".
- A framed picture by its description, loading or loaded.
This is what the browser reports to assistive technology. What each screen reader then says varies, and has not been listened to yet.
WCAG 2.2
| Criterion | Level | How this meets it |
|---|---|---|
| 1.1.1 Non-text Content | A | A framed picture keeps its description. |
| 2.2.2 Pause, Stop, Hide | A | The sweep is the only movement, and stops with reduced motion. |
| 2.3.3 Animation from Interactions | AAA | No sweep and no fade with reduced motion. |
| 4.1.3 Status Messages | AA | What is loading is said as a status, without taking the focus. |
The criteria this component has a part in. A page that uses it still has to meet the rest.
Checked
| Check | How | Result |
|---|---|---|
| Automated (axe-core) | WCAG 2.0, 2.1 and 2.2 rules at A and AA, the page in light and in dark | Passed Nothing found, light or dark |
| Narrow screen | No sideways scrolling at 320px wide (WCAG 1.4.10) | Passed No sideways scrolling |
| Keyboard and what the browser reports | Real key presses on the live example, and the role, name and state given to assistive technology | Passed 7 of 7 checks pass |
| On paper | Somnia’s print check: no overlaps, stranded headings or controls on the page | Passed No faults on 5 sheets |
| Screen reader | Listened to by a person, in VoiceOver and NVDA | Not yet Not yet checked by a person |
The 7 checks made with the keyboard, on the example at the top of this page:
- Passed A placeholder says what is loading once, as a status
- Passed Its shapes are hidden from screen readers
- Passed A framed picture is in the page with its description, loaded or not
- Passed A picture that can’t load keeps its place and shows no broken picture
- Passed A picture that has loaded is shown
- Passed Nothing in a placeholder or a frame is a stop for the keyboard
- Passed With reduced motion nothing sweeps or fades
Run by script on against Somnia DS 1.89.0, in Chromium with axe-core 4.14.0. How these checks work, and every component's results.
Not yet checked
- How it sounds in a screen reader (VoiceOver, NVDA, TalkBack) has not been checked by a person. The roles, names and states the browser reports are checked by script; what is actually spoken is not.
- Windows high contrast (forced colours) has not been looked at by a person.
- Nothing announces that the content has arrived: the placeholder’s label goes, and the content is simply there. Whether that is enough has not been listened to.
Evidence
Where it's used
| Where | For |
|---|---|
| Somnia CMS | Every page while it fetches: cards, rows, fields and the editor. |
| Every Somnia site | Media frames round pictures and videos that arrive after the page; img.sn-photo on the main picture of articles and case studies, and in galleries. |
What we saw, and what changed
| When | What we saw | What changed |
|---|---|---|
| A picture arriving late pushed the page about, and its description showed as stray words while it waited. | Media frames: the space is held, with the placeholder’s sweep and a mark, and the picture fades in (1.29.0). | |
| A light area on a dark page got the dark theme’s grey placeholders. | Placeholders take their colours from the theme of the area they are in (1.29.0). | |
| Under a brand set on the page, placeholders kept the root brand’s grey. | Their colours are worked out again under the brand (1.49.0). |
From building and using it on real sites, each entry taken from the changelog or the build's own notes. This is observation by the studio and its clients, not research sessions with users.
What we don't know yet
- How long people really wait on each page is not measured.