empty state

An empty state takes the place of a list or a panel that has nothing to show, and tells people why. A small line drawing, a title and a sentence say what is true and what they can do next.

when to use

• In place of a list, a table or a panel that has nothing to show, once you know why. There are five reasons, each with its own kind of message: nothing is there yet, nothing is left to do, the filters match nothing, the list couldn't load, or it can't be told yet.
• At the size of what it replaces: the small one inside a panel or a table (a data table shows it in its empty body), the medium one for a section, and the large one for a whole page.

when to use something else

• While the list is still loading. Use the loading state of the data table, or a spinner. Say “nothing here” only once you know it is true.
• Above content that still shows. For the rows from 4 minutes ago with an error on top, use a banner. It sits above the content and leaves it in place.
• For the state of one item, in a list that is otherwise there. Use a status in its row.
• To confirm an action that just finished. Use a toast, which says so and goes away.

anatomy

1. Container. A centred column that holds the rest, with room around it that grows with the size.
2. Illustration. A small line drawing of a square terminal window, in quiet lines, with one accent in the colour of the kind. It is decoration, so assistive technology skips it.
3. Title. What is true, in a few words, in monospace and shown in lowercase. It is a real heading, at the level that fits the page.
4. Description (optional). One or two sentences under the title, in the body face: why, and what people can do.
5. Actions (optional). Buttons under the text, centred.

variants and states

kinds

There are five kinds, one for each reason there is nothing to show. Pick the kind by what is true, not by the picture.

The empty kind and the done kind both mean “nothing here”, for opposite reasons: empty before anything has happened, done after everything has.

When the filters hide everything, use the search kind, not the empty one: the data is there, and the filters hide it. Empty states goes through which kind fits which situation, case by case.

sizes

There are three sizes, to match what the empty state replaces: small, medium (the default) and large. The drawing, the title and the room around them grow with each size.

actions

The actions are buttons: at most one for the emphasized action, and an optional second one, standard or quiet.

heading level

The title is a level-2 heading, unless you give it another heading level, from 2 to 6. Match the page's outline: inside a section whose heading is level 2, make the title level 3.

behaviour

• An empty state is static: people read it, and the only things in it that take focus are its actions.
• It doesn't announce itself when it appears. When it replaces a list because the filters changed, what a screen reader hears is the live count of results in the filter bar.

The full keyboard map is on the empty state's React page.

accessibility

• The illustration is decoration, hidden from assistive technology. The title says what is true.
• The title is a real heading, so people who move through a page by its headings find it. Give it the level that keeps the page's outline in order.
• The accent colour only repeats the kind. The words carry the meaning.

Today:

• Pressing the action usually removes the empty state, and the button with it, so focus falls back to the page: after “clear filters”, nothing has focus. Move focus yourself, to the search field for instance.
• Nothing holds you to one emphasized action: the empty state shows whatever actions it is given.

content

• Title. What is true, in a few words: “nothing missing”, “no matches”, “couldn't load”, “nothing tracked yet”, “nothing can be checked yet”. Lowercase, with no full stop.
• Description. One or two sentences, in sentence case: why, and what the person can do. “Nothing fits these filters.” “Import a list to start tracking.”
• Actions. One emphasized action at most. When the view already has its one emphasized action, in a toolbar for example, make this one a standard button.
• Tone. Calm: say what is true. No apology, no joke, no “oops”.
• The way out. Name it for each kind: “clear filters” for search, “try again” for error, and for unknown, the step that makes it known.

do and don't

related

• Empty states: which kind applies when, and what each one offers.
• Filter bar: its live count is what a screen reader hears when the filters leave nothing.
• Banner: a message above content that still shows.
• Data table: the list an empty state most often stands in for.

specs

• Container: a centred column, with its text centred.
• Illustration: an SVG line drawing on a 160 × 120 grid, scaled to the size's width: the window frame in --border-control, quiet lines in --border-2, one accent in the kind's colour. aria-hidden="true" and focusable="false".
• Title: title. A real heading, an h2 unless headingLevel sets another level, from 2 to 6. JetBrains Mono 600, line-height 1.3, --fg, lowercased with text-transform.
• Description: description, a paragraph. Inter 13px, line-height 1.55, --fg-muted, at most 46ch wide, 8px under the title.
• Actions: actions. Centred, 8px apart, wrapping, 16px under the text. Buttons: at most one variant="primary", and an optional second, variant="default" or variant="ghost". Nothing enforces a single primary.
• Announcing: none. It is not a live region.
• In a data table: the data table's empty prop takes it, and shows it in the table's empty body.