Empty & Error States

Reach for EmptyState when a list is genuinely empty, and ErrorState when a request failed. They are separate components on purpose: telling someone they have no items when the fetch merely broke is the one answer that is actually wrong, and it is the easiest mistake to make when both states share a branch.

Resolve the error case before the empty case:

Basic

With an action

Only offer one when creating the missing thing is actually possible here. A "New report" button on a "nothing shared with you" state is a dead end — nothing the user does on this screen changes that list.

Without a title

title is optional. On a subdued surface — one tab of a card, a small section — a headline plus a sentence usually says the same thing twice, and the sentence alone carries it. Keep the headline for page-level states, where the empty view has to stand on its own.

ErrorState is the exception: it always renders a headline, falling back to its own copy, because a failure the reader has to infer from one line of tertiary text is a failure they will read as an empty list.

Sizes

page stands in for a whole list view, section for a card or one tab of a list, and inline for small containers where reserving height would look wrong.

Error state

Point onRetry at the query that failed rather than a page reload — reloading discards everything else that loaded fine.

ErrorState renders with role="alert", so screen readers announce the failure. Pass role to override it.

Without a retry

Omit onRetry when there is nothing useful to retry — a crashed section, or a failure the user can only resolve by navigating away.