Skip to content

Empty State

Interactive specimen

Native controls work. Demo links and submissions stay inside this specimen.

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.

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.

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.