EmptyState
Preview appears after the next Storybook update.
<EmptyState />When to use
Use it for
- First use: nothing has been created yet (no tokens, no pull requests). Explain the value and offer the first step.
- No results: a search or filter matched nothing. Say what was searched and how to widen it.
- Cleared: the user finished everything (no reviews waiting). Confirm it calmly.
- size sm inside tables and cards, md in panels, lg for a whole page.
Not for
- Errors that stopped content from loading: use an Alert with a retry action.
- Content still loading: use Skeleton.
Do and don't
Every example is rendered with the real component, so it always matches what ships.
No pull requests yet
Changes you sync from Figma open a pull request here.
Say what goes here and how to get it
The title names the missing object, the description says where it comes from, the button starts it.
Nothing here
"Nothing here" with no way forward
It describes the screen the user already sees and leaves them stuck.
Accessibility
- The title is a real heading (headingLevel, default h3) so it appears in the page outline; pick the level that fits the page.
- The icon is decorative and hidden from assistive tech: the title carries the meaning.
- Actions are regular Buttons or Links in the tab order, after the text.
Content guidelines
- Title: what is missing, plainly: "No tokens match brand.700".
- Description: why it is empty and what fills it, in one or two sentences.
- One primary action at most, named with a verb: "Sync from Figma".
- No jokes or illustrations that delay the next step.
From the code Generated from the component, not editable here.
Anatomy and tokens
Read from packages/react/src/components/EmptyState/EmptyState.module.css at build time. Every value is a token: open one to see its alias chain in both themes.
- Container
.emptyState - Size sm
.sm - Size lg
.lg - Icon plate
.media - Size sm
.sm .media - Size lg
.lg .media - Text column
.text - Title (heading)
.title - Size lg
.lg .title - Description
.description - Size lg
.lg .description - Actions
.actions
Motion and interaction
EmptyState does not animate: its states change at once.
From the code Generated from the component, not editable here.
Props
Parsed from the TypeScript types in packages/react/src/components/EmptyState/EmptyState.tsx, so this table cannot drift from the code. It also accepts every native <div> attribute except title.
| Prop | Type | Default | Description |
|---|---|---|---|
titlerequired | ReactNode | none | What is empty, said plainly: "No pull requests yet". |
icon | LucideIcon | none | A Lucide icon that names the object that is missing (GitPullRequest for pull requests). |
description | ReactNode | none | Why it is empty and what fills it. One or two sentences. |
actions | ReactNode | none | The next step: usually one primary Button, plus an optional secondary Button or Link. |
size | 'sm' | 'md' | 'lg' | 'md' | `sm` inside a card or table, `md` in a panel, `lg` for a whole page. Default `md`. |
headingLevel | 2 | 3 | 4 | 5 | 6 | 3 | Heading level of the title, to fit the page outline. Default 3. |
align | 'center' | 'start' | 'center' | `center` for pages and panels, `start` inside left-aligned layouts. Default `center`. |
Playground
Change the props and see the real EmptyState update. Controls are generated from the TypeScript props; nothing here changes the system.
<EmptyState title="No pull requests yet" description="Changes you sync from Figma open a pull request here, ready for review." />Workbench
For contributors: every state with the accessibility panel, in the component workbench (Storybook). The stories double as visual test fixtures; the guidance on this page is the user documentation (open EmptyState in Storybook).
Embed Storybook stories here (3)
Loads from https://bridge-storybook.floriangouloubi.com (set STORYBOOK_URL at build time). If Storybook is not running, the frames stay empty.
Default
NoResults
AllStates
From the code Generated from the component, not editable here.
Changelog
- New
Feedback: Alert (five tones, actions, dismiss, correct live region), Toast (ToastProvider and useToast with success, error, warning, info, promise, update and close), Progress (linear and circular, determinate and indeterminate), Skeleton, EmptyState, plus Spinner stories and guidance
v1.0.0, Nov 11, 2026