Skip to content

Design system

Documentation

DesignPatterns / Empty & Error States

Patterns / Empty & Error States

Beta

Empty and error states

Empty, no-results, loading, and error states should explain what happened and point to the next useful action.

On this page

Examples

Empty and error states pattern

Choose the correct shared surface for empty, loading, error, and completed results.

No projects yet

Create the first project to give your team a place to start.

Tabs showing empty, no-results, loading, error, and success states

State model

Empty and error state guidance
StateMeaningNext action
emptyThe feature has no records yet.Create the first record.
no-resultsRecords exist, but the current query or filters match none.Clear or change the search/filter.
loadingThe result is being requested or refreshed.Keep context and prevent duplicate reloads.
errorThe request failed and the current result is not trustworthy.Explain the failure and offer Retry.

Copy

Write from the person’s point of view. Name the object, explain the condition in plain language, and use an action that says what will happen next. Avoid vague “Something went wrong” copy and avoid apologies that do not help recovery.

The runnable Preview and Code/Copy tabs use src/components/design/examples/source/empty-error-states-pattern.tsx. The recovery delay is a local fixture; this pattern has no public property playground.

  • Empty: “No projects yet” plus “Create project.”
  • No results: repeat the query or filter context and offer “Clear search.”
  • Error: say what could not load, preserve safe context, and offer “Try again.”

Accessibility

  • Keep the state heading in the document structure; do not communicate the state with an illustration or color alone.
  • Use role="status" for non-urgent loading/success updates and role="alert" only for an error that needs immediate attention.
  • Make Retry and the recovery action keyboard-focusable and keep the label specific.
  • Respect reduced motion. A spinner may be decorative, but the loading message must still be available as text.

Do and don’t

Do

Treat emptiness as an invitation to act and errors as a short path back to a trusted state.

Don’t

Show a blank container, hide the recovery action behind hover, or make the user guess whether data was deleted.

  • Button gives the recovery action a clear verb and loading state.
  • Card keeps a state message and its action together.
  • Accessibility documents the shared focus and contrast contract.