Content & Data
Empty State
Empty State is a zero-content placeholder with title, description, and optional recovery actions for collections, search, or first-use flows.
Single component
betaReact AvailableFigma AvailableDocs Partial
- React last updated
- 2026-07-13
- Documentation last updated
- 2026-06-01
- Accessibility target
- WCAG 2.2 AA (target)
- Version
- 0.5.0-beta
Known open questions
- No Results, Placeholder State, and Result Empty State are synonyms — Empty State is canonical.
- Permission-restricted empty states are not confirmed as a separate variant.
- Error states remain separate from Empty State.
Purpose
Communicating that a list, table, or content area currently has no data, with a clear next action to remedy that.
Anatomy
Empty State composes optional decorative icon, title, description, and Button or Link actions inside a section.
Variants and states
first-use · no-results · informational
When to use
Any list/table/collection view when it has zero items.
When not to use
Loading states — use Skeleton. Empty State means confirmed zero results, not still loading.
Accessibility
Should be announced via an aria-live region when it replaces a previously loading/populated view.
Common mistakes
Showing Empty State prematurely, before confirming data has finished loading.
Properties
Title (text), Description (text). Includes a real Button instance for the call-to-action.
When should an Empty State be shown?
After loading completes and a collection, search, or workflow genuinely has zero items — not while data is still loading.
What is the difference between Empty State and Alert?
Empty State explains absent content with recovery guidance. Alert communicates persistent status or errors inline.
How should “No results” be announced?
Announce from the surrounding results region when content changes dynamically — not from every child element.
Should an Empty State always include an action?
No — informational empty states may omit actions when no recovery step exists.
When should an illustration be hidden from screen readers?
When the icon or illustration is decorative and the title or description already conveys the message.
Tokens used
component/surface/content-mutedsemantic/text/primarysemantic/text/secondary
Component API
| Prop | Type | Default | Description |
|---|---|---|---|
| title | string | — | Visible heading and accessible section label. |
| description | ReactNode | — | Supporting guidance or recovery copy. |
| icon | ReactNode | — | Decorative Phosphor icon. |
| illustration | ReactNode | — | Optional illustration slot. |
| primaryAction | { label, href?, onClick? } | — | Primary recovery action. |
| secondaryAction | { label, href?, onClick? } | — | Secondary action or link. |
React example
Copy React example
import { EmptyState } from "@/components/ui/EmptyState";
export function Example() {
return (
<EmptyState
title="No components match your search"
description="Try a different term or clear active filters."
primaryAction={{ label: "Clear filters", onClick: () => undefined }}
secondaryAction={{ label: "Browse components", href: "/components" }}
/>
);
}