Empty state | Sodium design system

Reason

No pipelines yet
A pipeline loads a source into the warehouse on a schedule.
emptydefault
No tables match orders_v
Clear the filter to see all 214 tables.
no-results
You cannot see this warehouse
analytics_wh is limited to the finance role.
no-access
Could not load runs
Request req_8f2a91 timed out after 30 seconds.
error

When to use it

Use: A list, table or frame has nothing to show yet, and the person can make the first one.
Use: A search or filter matched nothing.
Use: The person cannot see this, or it failed to load.
Not for: It is still loading. Use Skeleton.
Not for: Part of a view failed and the rest is fine. Use Alert.

6 rules

Must: Set reason to why it is empty: empty, no-results, no-access or error. Because the reason picks the glyph, and error adds role="alert" and the failure colour.
Must: Give it at most one action, secondary unless it is the only way forward on the page. Because an empty region with two buttons asks the person to choose before they know what is there.
Never: Add an illustration, a big icon or a tinted tile. Because Sodium is rules and words; the glyph in its ruled square is all the picture an empty region gets.
Must: Use variant="plain" inside a frame, a list or a table. Because the framed variant draws its own edge, a box inside the frame.
Should: Show the request ID in EmptyCode on an error, so the person can quote it.
Should: Write the title as a sentence that names what is missing, in sentence case.

4 checks

: error is role="alert", so it is announced when it replaces the content.
: The title is an h3; give it the level the page needs with render or a heading of your own.
: Titles text-1 18.3:1, error titles fail-text 6.5:1, descriptions text-2 7.8:1; the glyph is aria-hidden.
: EmptyRetry keeps its box while pending and reports a failed retry in a status region.

3 edge cases

Narrow column: The description wraps at the hint measure; the action wraps under it.
Retry fails again: Says "Retry 2 failed at 14:03:12" beside the button.
Retry succeeds: The caller swaps in the content and moves focus to it.

5 props

reason: 'empty' | 'no-results' | 'no-access' | 'error' default 'empty'
variant: 'framed' | 'plain' default 'framed'
size: 'default' | 'sm' default 'default'
EmptyIcon icon: SodiumIcon
EmptyRetry onRetry: () => Promise

11 tokens