EmptyState

Molecule
Centered, calm, never blame the user. Always tell them what could be here, and ideally how to get there.
src/molecules/empty-state
View in Overlays & feedback

Playground

Every control sets a real prop of EmptyStateProps. The JSX below updates as you go.
No components match
Try another name or clear the filters.
Props
title
string
description
string
actionLabel
string
bordered
boolean
elevated
boolean
compact
boolean
success
boolean
JSX · EmptyStateProps
<EmptyState
title="No components match"
description="Try another name or clear the filters."
actionLabel="Clear filters"
bordered
/>

Variants

5 examples from src/molecules/empty-state/empty-state.md, each rendered live from its own JSX.
No users
Invite your first team member.
Bordered
<EmptyState
bordered
icon={<Icon users />}
title="No users"
description="Invite your first team member."
/>
No files
Upload or drag files here.
Action
<EmptyState
icon={<Icon fileText />}
title="No files"
description="Upload or drag files here."
actionLabel="Upload files"
/>
No activity
Events will appear as they happen.
Compact
<EmptyState
bordered
compact
icon={<Icon chartLine />}
title="No activity"
description="Events will appear as they happen."
/>
No errors
Everything is running smoothly.
Success
<EmptyState
success
icon={<Icon circleCheck />}
title="No errors"
description="Everything is running smoothly."
/>
Name
Email
Role
No results found
Try adjusting your search filters.
Inside a table
The empty state's action resolves the emptiness it describes: pressing "Clear filters" drops the filter, so the rows return and the empty state leaves with it. (Stateful is a docs-only helper standing in for your own state; in an app you would hold the filter with useState and clear it in onAction.)
<Stateful initial={true}>
{(filtered, setFiltered) => (
<DataTable
columns={["Name", "Email", "Role"]}
rows={filtered ? [] : [
["Alice Johnson", "alice@example.com", "Admin"],
["Bob Smith", "bob@example.com", "Editor"],
["Rachel Chen", "rachel@example.com", "Admin"]
]}
emptyMessage={
<EmptyState
icon={<Icon search />}
title="No results found"
description="Try adjusting your search filters."
actionLabel="Clear filters"
onAction={() => setFiltered(false)}
/>
}
/>
)}
</Stateful>

Anatomy

No components match
Try another name or clear the filters.
1
Container
2
Icon
3
Title
4
Description
5
Action
Dimmed parts appear only in some states or variants.

Props

11 props on EmptyStateProps, grouped as they are declared in source. Required props are marked *.
Prop
Type
Default
Description
Props
5 props
icon
string | ReactElement
–
The glyph shown in the disc: a monochrome <Icon /> element (cloned with the tone's tint and the disc's glyph size, so it follows success/default like the disc wash does; a semantic color boolean on the element still wins) or an emoji/character string.
title
string
–
Short, neutral headline naming the empty result.
description
string
–
One reassuring line, ideally pointing at the next step.
actionLabel
string
–
When set, renders a secondary action button below the description (small when compact).
onAction
() => void
–
Called when the action button is pressed.
Tone axis
pick one
1 prop
success
boolean
false
Container axis
2 props
bordered
boolean
false
elevated
boolean
false
A shaded card: the card fill under the medium shade.
Density axis
3 props
compact
boolean
false
testID
string
–
E2E hook forwarded to the root element.
style
LayoutStyle
–
Composition within a parent only, never a restyle hook and never a width: the parent layout container provides the bounds.

Accessibility and keyboard

Keyboard
Enter
Activates
Space
Activates
Tab
Moves focus on
Semantics
ARIA on web
aria-hidden
Below the platform minimum, the touch area grows to 44 pt on iOS and 48 dp on Android without moving the layout.

Platform skins

The playground's props on each platform: same tree, native shapes, type and touch sizes.
No errors
Everything is running smoothly.
Web
control 10 · field 10 · card 16 · Instrument Sans
No errors
Everything is running smoothly.
iOS
capsule controls · field 8 · card 12 · SF Pro · 44 pt
No errors
Everything is running smoothly.
Android
Material 3 stadium · field 4 · card 12 · Roboto · 48 dp

Usage

<EmptyState
icon={<Icon search />}
title="No results found"
description="Try adjusting your search filters."
/>
The column is padded 40 by 24 at an 18px corner with a 12px rhythm: a 52px glyph tile in the accent's soft wash, a 19px display-face title, a muted 14px description capped at 320px, and a secondary action. bordered draws a dashed edge, elevated lifts it onto a shaded card, and compact tightens the padding, rhythm, tile and title for a table cell.

Tokens

Read from the playground render. Values follow the scheme and the ion hue.
--bls
--bw
--f-dp
--fd
--ft
--hl
--ion-soft
--ion-tx
--ln2
--sf3
--tx
--tx2

Related components