Empty State
Native controls work. Demo links and submissions stay inside this specimen. This example scrolls horizontally at this width.
Source markup
<!-- @dsCard group="Feedback" height=700 -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Empty state</title>
<style>
.demo { display: grid; gap: var(--space-md); padding: var(--space-sm); }
.demo__states {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(min(100%, calc(var(--space-3xl) * 3)), 1fr));
gap: var(--space-md);
}
/* Static copy of the action's real focus rule. */
.empty-state__actions .btn.is-focus {
outline: var(--focus-width) solid var(--focus-ring);
outline-offset: var(--focus-offset);
box-shadow: var(--shadow-focus-ring);
}
</style>
</head>
<body>
<main class="demo">
<h1 class="t-h3">Empty state</h1>
<p class="field__help">Static examples. These buttons illustrate actions; they do not create records, clear filters or retry a request.</p>
<div class="demo__states">
<section class="empty-state" aria-labelledby="nz-empty-data-title">
<p class="t-label">No data</p>
<h2 class="t-h4" id="nz-empty-data-title">No notes yet</h2>
<p class="empty-state__description">Add a note to start this list.</p>
<div class="empty-state__actions">
<button class="btn btn--primary" type="button">Add a note</button>
</div>
</section>
<section class="empty-state" aria-labelledby="nz-empty-filter-title">
<p class="t-label">No matching results / focus visible</p>
<h2 class="t-h4" id="nz-empty-filter-title">No notes match these filters</h2>
<p class="empty-state__description">Clear the filters to see all notes, or change the search terms.</p>
<div class="empty-state__actions">
<button class="btn btn--ghost is-focus" type="button">Clear filters</button>
</div>
</section>
<section class="empty-state" aria-labelledby="nz-empty-retry-title">
<p class="t-label">Load failure</p>
<h2 class="t-h4" id="nz-empty-retry-title">Notes could not be loaded</h2>
<p class="empty-state__description">Try loading the list again.</p>
<div class="empty-state__actions">
<button class="btn btn--ghost" type="button">Try again</button>
</div>
</section>
<section class="empty-state" aria-labelledby="nz-empty-offline-title">
<p class="t-label">Retry unavailable / disabled</p>
<h2 class="t-h4" id="nz-empty-offline-title">Waiting for a connection</h2>
<p class="empty-state__description" id="nz-empty-offline-help">Reconnect before trying to load the notes again.</p>
<div class="empty-state__actions">
<button class="btn btn--ghost" type="button" disabled aria-describedby="nz-empty-offline-help">Try again</button>
</div>
</section>
</div>
</main>
</body>
</html>
A short explanation and a useful next action where content would normally appear. Distinguish an empty list, a filtered list with no matches and a failed load. An empty result does not establish that a service is healthy or that data was deleted.
Structure and copy
Section titled “Structure and copy”Use a .empty-state section with a heading, a .empty-state__description and, when useful, .empty-state__actions. Bind aria-labelledby to the heading’s unique ID. Choose the heading level from the page outline; the standalone preview uses an h1 followed by h2 examples styled with .t-h4.
For no data, say what is absent and how to add the first item. For no matches, identify the active filtering and offer to clear or change it. For a failed load, say the content could not be loaded and offer a retry. Name a cause only when the application knows it; the connection example assumes a confirmed unavailable connection.
Use a native button for an action on the current page and an anchor with a real destination for navigation. Give the action a specific label. The surface, border and text reuse color-semantic-bg-surface, color-semantic-border-base and color-semantic-text-muted. There is no decorative status colour or icon required.
States and accessibility
Section titled “States and accessibility”Actions reuse .btn with primary or ghost styling. Text wraps on narrow screens, keyboard focus uses shadow-focus-ring and the token outline, and native disabled prevents activation and keyboard focus. Explain the unavailable action in visible text and associate that explanation with aria-describedby. Disable retry only while there is a real reason; the application must restore it when available.
Sections themselves are not focusable controls. Do not add role="alert" to every empty state. For results replaced dynamically, the application should announce a concise update and manage focus if the triggering control disappears. Keep headings and actions discoverable in normal reading order.
The HTML/CSS preview is static: it does not validate, submit, add data, clear filters or retry requests. Enabled buttons demonstrate appearance and native keyboard activation only. Consumers provide those behaviours, loading state and failure recovery; do not present sample outcomes as service guarantees.