Empty state
An empty state appears wherever a view, table, list, or section has no content to show. Rather than a blank area, it confirms the system is working and — where it can — moves the reader forward.
Empty states aren't decorative. Each one is a chance to teach the reader what the surface is for.
The three questions
A reader should be able to answer all three instantly:
- What am I seeing here?
- Why am I seeing this?
- What can I do next?
If the state can't answer the third, say so plainly rather than inventing an action — see Action below.
Three kinds, three jobs
The kind determines what the copy has to do. Getting this wrong is the most common failure: writing first-time-use copy for a filter result.
| Kind | When it happens | What the copy must do |
|---|---|---|
| First-time use | The reader is seeing a feature for the first time | Explain the feature and help them take the first step |
| User action | A result of something they did — filters, search, a time range | Explain why there are no results, and offer a way back |
| Error | Data could not be retrieved — permissions, an outage | Say why, and give a next step if one exists — change permission, reload |
Recovered from the predecessor
reference-guide, which carried this taxonomy and the three questions. The live site's page has anatomy only. The live guidance isn't wrong — it covers too narrow a slice.
Anatomy
- Icon — a Font Awesome icon representing the context (a search icon for no results, a bell for no notifications). Muted, so the tone stays informational rather than alarming.
- Title — short, and framed positively. "Create a public uptime page", not "You have no public status pages".
- Subtitle — one sentence of context, or what the reader can do to populate the view.
- Action (optional) — a button toward the next step. Omit it when the state is purely informational and no action can resolve it — "No errors in the last 24 hours" is good news, not a task.
Copy
One short sentence on what's missing, one button that moves forward. Sentence case, verb-first labels.
pm:design/ux/empty-and-error-states.md holds drafted copy for six named product situations — zero apps, waiting for first data, an uninstrumented service, an empty dashboard, filters returning nothing, no alerts configured. It is unmaintained and downstream of this guidance, so treat those as candidate instances to review, not as approved strings. The post-install states matter most: that is where activation is won or lost.