EmptyState

The <EmptyState> component is used to communicate that a container, list, or page currently has no data to display. It provides visual confirmation that the lack of data is a valid system state, ensuring users do not mistake the empty space for a loading error or a bug.

It serves as a bridge between an empty screen and a populated one, offering context and guidance.

Anatomy

An <EmptyState> is a centered column holding the built-in illustration, a title, an optional description, and an optional action.

• Container: Centered column, capped at a readable width. It paints no surface of its own, so it sits directly on whatever is behind it.
• Illustration: Built into the component and marked aria-hidden, so it carries no meaning on its own. It is fixed and cannot be swapped out.
• Title: Required. Renders as a semantic heading, <h3> by default. Adjust the level with the headingLevel prop so it fits the surrounding document outline.
• Description (optional): Short explanation of why there is nothing to show, and of what would put content here.
• Action (optional): The next step, usually a single <Button>. See Actions for which variant it should use.

Appearance

The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.

Usage

The <EmptyState> component is ideal for scenarios where a user might expect to see content, but the data set is empty despite a successful page load.

Use this component to confirm that the lack of data is a valid state in the following situations:

• Initial States: When a user visits a feature or dashboard for the first time and has no data due to a lack of activity.
• User-Cleared States: When a user has successfully resolved, deleted, or triaged all items in a list.
• No Results (Search & Filter): When a list or table is empty because no items match the current search query or applied filters.

Actions

Add an action when the empty state has a concrete next step. A filtered or searched list needs a way back to the full set, and an initial state needs a way to create the first record. A state the user emptied on purpose often has no next step at all, and then the action is better left out than filled with something vague.

Keep it to one primary action. An empty state that replaces the content of a page can carry the page's primary action, but only when nothing else already does. The app frame keeps the <Page.Header> in place when the content below it is empty, so if that header still holds the primary action, the empty state should not repeat it. When an empty state has two actions, they run primary → secondary from left to right. The action prop renders whatever it is given as a single block and adds no spacing between children, so wrap a pair of buttons in an <Inline>.

For the general rule behind all of this, see Button: Visual hierarchy, Placement and order, and Surface actions.

Best Practices

Timing is critical when displaying empty states. Always show a loading indicator (Skeleton or Spinner) while data is being fetched, and only reveal the empty state after the request completes and confirms no results exist. This prevents the "Flash of Empty Content" - a jarring flicker that can confuse users and make the interface feel unstable.

It's equally important to distinguish between empty and error states. Use the <EmptyState> component exclusively for successful operations that return no data. For system failures, network errors, or other exceptions, use an ErrorState instead (see the error boundaries pattern). This clear separation helps users understand whether they need to take action or simply recognize that no content exists yet.

Content Strategy

Effective <EmptyState> content serves as a conversation with the user, bridging the gap between a blank screen and their first successful interaction. Since an empty screen can be mistaken for a system error, the messaging should immediately reassure users that everything is functioning as expected. The text must confirm that the application is working correctly and that the lack of data is a valid state.

Accessibility

The <EmptyState> component is accessible by default through its required title, which renders as a semantic heading (<h3> by default) so screen reader users can navigate to it. Adjust the level with the headingLevel prop so it fits the surrounding document outline. The decorative illustration is marked with aria-hidden="true", ensuring assistive technologies correctly ignore it and focus on the meaningful text content.

Props

EmptyState

Alternative components

• Loader: Use for loading states before data is fetched. Unlike EmptyState, loaders indicate that content is actively being retrieved and will appear shortly.

• ErrorState: Use for failures. When data retrieval or rendering breaks, ErrorState replaces the content area and offers a way to recover. See the error boundaries pattern.