---
title: "Empty and first use"
description: "What a health surface shows when it has no value, and why the different kinds of nothing must never look alike."
url: "https://opsinjs.pensievelabs.org/docs/patterns/empty-and-first-use"
source: "https://opsinjs.pensievelabs.org/docs/patterns/empty-and-first-use.md"
section: "Patterns"
kind: "pattern"
aliases: ["empty state", "zero data", "nothing to show", "first use screen", "no readings yet"]
---

A blank tile, a dash and a "0" are three different assertions. "0 steps yesterday" is not the same fact as "no step data for yesterday".

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

Use it whenever a health surface renders with no value to show.

Do not use it when:

* The data exists but is old. That is [Offline and stale data](./offline-and-stale-data.mdx).
* The reader has never opened the product. That is [Onboarding and first run](./onboarding-and-first-run.mdx).
* A trend has too few points to support a direction. See [Trend review](./trend-review.mdx).

## How it works [#how-it-works]

A measured zero is a value, shown with its unit. Every other absence renders its reason:

| Kind of nothing        | Render                                       | Never imply                    |
| ---------------------- | -------------------------------------------- | ------------------------------ |
| Loading                | A skeleton in the final layout's shape       | A value                        |
| Never collected        | One sentence of value and exactly one action | Nothing to worry about         |
| Nothing in this filter | Say so, and offer to widen it                | They stopped logging           |
| Pending                | What is expected, and by when                | It is late or lost             |
| Failed to load         | An error with a retry                        | The value is zero or unchanged |
| Withheld               | What is off, and how to turn it back on      | The data was deleted           |

* Never render an absent value as a number: no zero, no dash styled as data, no last-known value dressed as current.
* Never present a failed request as "no data yet". That is a fact about your network, not about the reader.
* Absence has no clinical status, so an empty tile carries no status colour. See [Two colour axes](../health/two-colour-axes.mdx).
* Loading has a floor and a ceiling. Never flash a skeleton, and after a stated timeout show an honest error.

## Components [#components]

* [EmptyState](../components/empty-state.mdx) requires a `reason`: `nothing-yet`, `no-matches`, `nothing-left`, `not-enough` or `could-not-load`. Only `could-not-load` draws a marker of its own, and its action is mandatory.
* [Skeleton](../components/skeleton.mdx) holds the layout while loading, and `appearAfterMs` stops it flashing on a fast load.
* [CareCard](../components/care-card.mdx) says when a pending result is expected.
* [MetricTile](../components/metric-tile.mdx) with `value={null}` keeps its label and never shows a zero.

## Content [#content]

* One fact, one action, one reason: "No blood-pressure readings yet. Log one and we'll show it against your range." "No data" says nothing.
* No jokes about missing health data.
* An error owns the problem: "We couldn't load your readings. This is a problem on our side. Try again."

## Accessibility [#accessibility]

* The empty state has a heading at the level the content would have had, so the outline keeps its shape.
* Skeletons are `aria-hidden`, and the caller mounts one polite status message for the change. An error the reader might act on is announced assertively (WCAG 2.2 SC 4.1.3).
* The single action is the first focusable element after the heading.
* Illustrations are decorative, and nothing animates to fill the space.
