EmptyState
StableExplains why a view has no content yet and invites the action that fills it. An empty screen is a starting point, not a dead end.
No pull requests yet
Changes you sync from Figma open a pull request here, ready for review.
No pull requests yet
Changes you sync from Figma open a pull request here, ready for review.
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.
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
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 |
|---|---|---|---|
title required | 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.
No pull requests yet
Changes you sync from Figma open a pull request here, ready for review.
<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
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. Adds alert and skeleton component tokens.
Unreleased (current version 0.1.0, no release tagged yet) , Oct 17, 2026