Skip to main content
On this page

Empty states

Say why a space is empty, and what to offer as the way out.

Overview​

An empty state is what a list, table or panel shows when it has nothing in it. The same blank space might mean nothing has been added yet, that a search found nothing, that a filter is too narrow, that something failed, or that there's genuinely nothing to deal with.

This pattern covers what to say in each case, and what to offer as the way out.

The core decision​

What to show depends on why the space is empty, so work that out before writing anything.

  • Nothing added yet. Say what will appear here, and offer the action that creates the first one.
  • A search found nothing. Confirm the search ran, name what was searched for, and offer a way to broaden it.
  • A filter excluded everything. Make clear the filter is responsible rather than the data, and offer to clear it.
  • Nothing needs attention. This is likely good news, so use the opportunity to reassure: confirm the work is clear, and offer no action because there's nothing to do.
  • Something failed. Don't dress a failure as emptiness. See Errors are not empty states below.

Use Empty State for all of these except a failure.

Loading...
Edit live code
() => {
  // ignore - for live code example only.
  const [filtered, setFiltered] = useState(true);

  return filtered ? (
    <EmptyState
      title="No payments match these filters"
      description="Clear the filters to see all payments on this account."
      action={{ label: 'Clear filters', onClick: () => setFiltered(false) }}
    />
  ) : (
    <SummaryList>
      <SummaryItem label="24 July 2026">Direct Debit</SummaryItem>
      <SummaryItem label="22 July 2026">Card</SummaryItem>
    </SummaryList>
  );
}

Errors are not empty states​

There's a difference between showing nothing because there is nothing to show, and showing nothing because data could not be retrieved. Treating these the same can have real consequences for customers, for instance, a user who reads 'No payments found' will tell the customer they have no payments. If the service is actually down, that's a false statement about someone's account. Don't use an empty state for a failure.

The same goes for anything else that isn't really emptiness.

Fitting the space​

How much to show depends on how big the space is. Empty State gives you a centred icon, a bold title, a description and room around them, which suits a whole page or a main content region. In a small panel, a card, or a single field, plain text reads better.

Where more than one Empty State component would be visible in the viewport at once, for instance on a dashboard page, keep Empty State for the main region and give the others plain text.

Accessibility​

  • Replace the thing that was empty rather than sitting beside it. An empty table shouldn't render its column headers and footer, or a screen reader user will hear the whole table structure before reaching the message saying there's nothing in it.
  • title renders as bold text, not a heading. Someone navigating by heading won't land on it, so where an empty state replaces a whole page or a major region, put a real heading above it.
  • Announce the change when content becomes empty. Filtering a table to zero changes the page without moving focus, so a sighted user sees the rows vanish while a screen reader user hears nothing. Convey it through a live region, or move focus to the message. This is our own position rather than established practice.
  • The icon carries no information. Empty State renders a decorative search icon, already hidden from assistive technology, so the title and description have to carry the whole message.

Copy guidance​

Keep it short enough to read at a glance, and cover one next step rather than several. Where there are genuinely several options, pick the most likely and let the rest be found elsewhere.

Be specific​

Name the thing, and where there was a query, name that too.

Do

No results for 'J Smith'

Don't

No results

Say the filter is responsible​

Otherwise someone may conclude the data is missing.

Do

No payments match these filters

Don't

No payments found

Related​

References​