Empty state

v1.0.0 | View in Storybook

​

When to use

• First-time scenarios & user cleared: use an Empty state where the user may not have data. An Empty state is a great way to explain what they can do to populate the screen and provide the call to action. If it’s a user-cleared scenario, for example, they finished their to-dos or cleared an inbox, an Empty state might be positive and celebratory or encouraging of what to do next.
• No results: when a user searches for data, but the system cannot return any results, an Empty state is a great form of feedback to the user. Help them understand how best to modify their search.
• Error management: when something did not go as planned an Empty state can help guide the user back to the right path. Error messages paired with thoughtful guidance content can help the user resolve the error on their own or seek out the appropriate support channels. Error management might include permission issues, system issues or configuration required.

​

When to use something else

Empty states are patterns with no established alternatives for their use cases. However, it’s important to think critically about the Empty states and potential scenarios where restricting access may be a simpler approach. For example: if a user has access to many views within a page but all views are empty as a first-time user, it might be best to limit access to only the page where the first call to action is if such exists. Consider how seeing several empty state pages repeated could potentially frustrate a user. Alternatively, creating more custom content for each empty page could be more welcoming and helpful to the user.

​

Dos and don’ts

• Do include a primary call to action Button to help guide the user to act fast. Use secondary buttons to provide a way back to a previous screen (if applicable) or to link to additional documentation.
• Do use illustrations that reflect the situation.
• Do use a default size for full pages or large containers. Use a compact size for small containers or Drawers and side panels.
• Don’t use product-specific terms that the user may not yet understand or discuss content that is not relevant to that page.
• Don’t adjust the styling or add alternative backgrounds to the container.
• Don’t cover multiple call to actions in one Empty state. If there are multiple things a user can do, pick the most important and keep the focus on that action.

​

Placement and alignment

Empty states always appear in the otherwise empty space, in the context of missing data. They can occur anywhere data is typically displayed, including but not limited to Tables, Cards, Menus, full pages and side panels. In general, content should be center-aligned, both horizontally and vertically, within their container.

​

Behavior

• Occupies the primary content region until the user resolves the empty or error condition; primary CTA should map to the next constructive step.
• Illustrations and copy are static guidance, not a substitute for Banner or Alert for live system faults unless paired appropriately.
• Use partial data reloads: Trigger data fetching only for the specific component or section where the error or empty state occurred (e.g., refresh a side panel, not the entire app).
• Keep user input/preferences intact: Preserve things like selected filters, zoom levels, or scroll position when retrying.
• Visual feedback: Show a spinner or loading skeleton during retry. Disable retry button while request is in progress to avoid duplicate calls.

​

Often used with

Primary (and optional secondary) Button; illustration or icon slot; headings/copy—pair with Search or filters when “no results” depends on query.

​

Accessibility

​

Semantic hierarchy and context

• Match surrounding heading levels: Assign the empty state title the correct heading level (<h2>, <h3>) relative to its parent container rather than hardcoding arbitrary levels.
• Maintain parent landmarks: Render the empty state inside its parent region (for example within <main>, <section>, or a Data grid container) so screen reader users retain section context when navigating by landmarks.

​

Dynamic state changes and focus

• Use live regions for filtered results: If the empty state appears dynamically (for example a search query returns zero results), wrap the container or status text in an aria-live="polite" region or role="status" so the change is announced automatically.
• Prevent focus loss on deletion: If deleting the final item in a list triggers the empty state, manually shift keyboard focus to the empty state container (tabIndex={-1}) or its main call-to-action button to prevent focus from resetting to the top of <body>.

​

Media and actionable elements

• Hide decorative graphics: Ensure decorative illustrations or SVGs carry aria-hidden="true" or alt="" so screen readers skip straight to the title and explanation.
• Use explicit CTA labels: Provide self-descriptive text for action buttons so they make sense when read out of context (for example “Clear active search filters” instead of “Reset”, or “Create your first project” instead of “Add”).

​

Visual examples

The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

​

Compact variant

Use the compact Empty state variant in small containers—such as a side panel, table cell, or drawer—where a full-page illustration would overwhelm the layout.

​

Full variant

Use the full Empty state variant on pages or large content areas when you have room for an illustration, heading, description, and a primary call to action.

​

Full variant types

Choose among full Empty state types—such as first-time, no results, or error—to match the scenario and set the right tone for copy and illustration.

​

Full variant custom icon

Replace the default Empty state illustration with a custom icon when a product-specific metaphor fits better than the built-in artwork.

​

With action

Include a primary Button in the Empty state when users can resolve the empty condition directly—for example, Create item or Clear filters.

​

No results

Use the no-results Empty state when a search or filter returns zero matches, and suggest how users can broaden or change their query.

​

With custom message

Customize the Empty state message when the default copy does not fit—for example, permission errors, maintenance windows, or domain-specific guidance.

​

Title as

Set the Empty state title element—for example, h2 instead of h3—to match the heading hierarchy of the surrounding page for correct document outline.