How to build an accessible EmptyState in React
Presentational by role; the title carries the meaning as text and the action is a real focusable control, so keyboard and screen-reader users can act on the next step
When to use a EmptyState
- Filling a view that has no data with guidance and a primary next step
- Explaining why a list/table is empty (no results, nothing created yet)
- Offering an action that resolves the empty condition (action prop)
When not to use it
- Content is still loading — use Skeleton or Spinner
- An error occurred — use Alert to explain the failure
Accessibility
Role none, verified at WCAG 2.2-AA.
Common mistakes
Avoid: Showing an EmptyState while data is still fetching
Prefer: A Skeleton during load, then EmptyState only if the result is empty
Conflating loading with empty tells the user there is no data when there may be
Example
<EmptyState title="No results" description="Try adjusting your filters." />