Empty-state component overview
Use empty states when the absence of content is meaningful enough to deserve guidance, including a region that failed to load and needs a retry. While content is still loading, use a spinner or skeleton instead.
When to use
Use empty states when
- A page or section has no data yet and people need orientation
- A first-time experience needs guidance before content exists
- The interface should explain what is missing and what action can create content
- Content failed to load and the region has nothing else to show, so people need to know what failed and how to retry
Do not use empty states when
- Content is still loading and a spinner or skeleton is more accurate
- The message is about content that is still on screen, such as a failed save or stale data; use an alert instead
- The page already contains enough surrounding guidance to explain what is happening
Patterns
Anatomy
Empty-state component anatomy
Design guidelines
Use empty states to orient people quickly, explain why nothing is shown, and make the next step obvious.1
Start with the reason
Explain what is missing or unavailable before telling people what they can do next.
2
Add only necessary detail
Use a short description when the title alone is not enough to reduce uncertainty or guide the next action.
3
Match the scale to the layout
Use
small, medium, or large based on the available space and the prominence the empty moment needs.Center the empty state within the available area when it represents the main content of the page or section, so the message is easy to notice without competing with unrelated UI.
Usage
Default
Use the default variant when you want the cleanest possible presentation and the title already communicates enough context.Options
With body
Use body content when the empty state needs a short explanation or a little more guidance about what happens next.With call to action
Use the footer when the empty state should help people recover immediately. Prefer one primary action. Add a secondary action only when it offers a clearly different path.Error with retry
When content fails to load and the region has nothing else to show, the failure is the region’s state. Replace the default icon with a warning icon, say what failed and what people can do, and offer Retry as the single action. Keep Alert for messages about content that is still on screen, such as a failed save or stale data.Sizes
Choose size based on the available space and the prominence of the moment.medium is the default and works for most dashboard or section-level empty states.
Allowed size values: small, medium (default), large.
Best practices
DoCombine a clear title with a short description when people need extra context. A title alone is often not enough to guide recovery.
Don’tDo not leave people with a vague message that explains nothing beyond the fact that the page is empty.
DoUse one clear primary Button or link to show the most useful next step.
Don’tDo not add too many competing calls to action. Too many choices weaken the guidance the empty state is supposed to provide.
DoUse a representative icon or illustration and place the empty state where it is easy to notice, usually centered within the available space.
Don’tDo not use decorative art that suggests the wrong situation or distracts from the actual message.
DoMatch the empty state size to the available layout so the message feels intentional instead of oversized or easy to miss.
Don’tDo not use a full-page large empty state inside a compact panel or card where it overwhelms the surrounding layout.
Accessibility
- Keep visuals decorative unless they carry meaning — if the thumbnail is only illustrative, you must hide it from assistive technology with
aria-hidden="true"or an emptyaltvalue. - Make the title and body self-sufficient — the title and body must let people understand the state without inferring meaning from the artwork.
- Use semantic, keyboard-accessible actions — any recovery path in the footer must be a real button or link that can receive focus and has a clear label.
- Preserve reading order — title, description, and actions should follow a logical visual and DOM sequence.
- Do not rely on color or imagery alone — the message itself must explain what is happening and what can be done next.
Keyboard interaction
No keyboard interaction: the component is not focusable. Actions you place in thefooter slot keep their own keyboard behavior.
Rules
API reference
Properties
Invalid combinations
No invalid prop combinations.Slots
Shadow parts
CSS custom properties
Resources
Interactive playground
Explore Empty State examples and sizes in Storybook
Source code
View the component source on GitHub