---
title: "EmptyState"
description: "What a screen shows before there is anything on it. It says plainly why it is empty and gives you one clear thing to do about it."
url: "https://opsinjs.pensievelabs.org/docs/components/empty-state"
source: "https://opsinjs.pensievelabs.org/docs/components/empty-state.md"
section: "Components"
status: "shipped"
kind: "component"
category: "feedback"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["blank slate", "no data", "nothing here", "zero state"]
governedBy: ["consent-and-privacy", "trends"]
usedIn: ["consent-and-permissions", "daily-logging", "empty-and-first-use", "onboarding-and-first-run", "trend-review"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="empty-state"
  status="shipped"
  questions="[
  &#x22;Whether an empty state may carry a primary action the reader cannot yet take, such as during a device sync.&#x22;,
  &#x22;Whether an illustration ever helps beside an absence of somebody's own health data has not been researched here.&#x22;,
  &#x22;A view that becomes empty should be announced once, but this component mounts no live region and nothing says what the region does.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="empty-state" unbuilt="false" importPath="@/components/ui/empty-state" registryDependencies="[&#x22;button&#x22;, &#x22;link&#x22;]" />

```tsx
import { EmptyState } from "@/components/ui/empty-state"
```

```tsx
<EmptyState
  reason="nothing-yet"
  title="No readings yet"
  action={{ label: "Add a reading", href: "/readings/new" }}
>
  Once you add your first reading it will be here, with the range your product
  compares it against.
</EmptyState>
```

## Examples [#examples]

<ComponentPreview name="empty-state" />

### A filter matched nothing [#a-filter-matched-nothing]

`reason="no-matches"` with an `onSelect` that clears the filter. The list owns the
live region and moves focus when the control unmounts.

<ComponentPreview name="empty-state-a-filter-matched-nothing" kind="example" align="start" />

### What happens when nobody wrote the body [#what-happens-when-nobody-wrote-the-body]

The first card has no `children`, so it admits the app does not say why and
warns. The second has two sentences.

<ComponentPreview name="empty-state-no-copy-supplied" kind="example" align="start" />

### An illustration, and what it is not allowed to do [#an-illustration-and-what-it-is-not-allowed-to-do]

`illustration` is `aria-hidden` and `inert`, hidden in print and below 17rem.
Cover it and the state still reads whole.

<ComponentPreview name="empty-state-with-an-illustration" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;Nothing added yet, where the fastest help is the first step.&#x22;,
  &#x22;A filter or search that matched nothing, where the reader must know it was the filter, not the data.&#x22;,
  &#x22;A view that cannot yet draw honestly, such as a trend with too few readings.&#x22;,
]"
  avoid="[
  { case: &#x22;The content is loading and will arrive shortly.&#x22;, instead: &#x22;skeleton&#x22; },
  { case: &#x22;The whole view failed, rather than one surface that could not load.&#x22;, instead: &#x22;alert-banner&#x22; },
  { case: &#x22;There is content, but it needs a caveat.&#x22;, instead: &#x22;callout&#x22; },
  { case: &#x22;Permission is needed before anything can be shown.&#x22;, instead: &#x22;consent-sheet&#x22; },
  { case: &#x22;One value is missing inside a full surface.&#x22;, instead: &#x22;value&#x22; },
]"
/>

## Accessibility [#accessibility]

Neither colour axis is used, so nothing can mix. `titleLevel` renders a real `h2` to
`h6`, default `2`, so check it against the outline. The `could-not-load` flag carries
its meaning in a word beside an `aria-hidden` icon, not colour, and the `href` action is
an anchor floored at `var(--opsin-target-minimum, 2.75rem)` on both axes. The default
preview renders clean on `/view`, and the audit changed nothing.

**Residual items.**

* No live region mounts, by design. On a stateless, read-only render one could only
  mis-fire, since it announces only changes made after first paint. The announcement
  belongs to whatever region changed, which the caller owns, as the filter example shows.
* The three example files were audited from source alone.
* Contrast against the card surface is unmeasured, and the report below carries it.

<KeyboardTable
  name="empty-state"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves focus to the action, then to the quieter alternative&#x22;,
    notes: &#x22;Nothing else is focusable. No action means no tab stop.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Moves focus back through the same controls&#x22;,
    notes: &#x22;Reverse order matches visual order.&#x22;,
  },
  {
    keys: &#x22;Enter&#x22;,
    action: &#x22;Activates whichever control has focus&#x22;,
    notes: &#x22;href follows the destination, onSelect calls the handler.&#x22;,
  },
  {
    keys: &#x22;Space&#x22;,
    action: &#x22;Activates the onSelect form only&#x22;,
    notes: &#x22;The platform's button and link distinction. No page scroll.&#x22;,
  },
  {
    keys: &#x22;After activation&#x22;,
    action: &#x22;The caller's, not this component's&#x22;,
    notes: &#x22;An onSelect that unmounts the state drops focus to body. Move it.&#x22;,
  },
]"
/>

<ContrastReport component="empty-state" />

## Props interface [#props-interface]

<PropsTable name="EmptyStateProps" />

`reason` and `title` are required. There is no exported `EmptyReason` type, so
name the union `EmptyStateProps["reason"]`. A blank `title`, a body with no
text or only a number, and an action with nothing to do each render a fallback and
warn once. A `secondary` with no `action` also warns.
