Empty states

Empty states convey the fact that there is nothing to list, perform, or display on the current page. Ideally, they also provide a clear action for the user to take.

Best practices

No data

There are two ways an empty state may be displayed in cases where there is no data:

• Initial state: no data to begin with
• Zero results: no data after a search or filter

Initial state

Perhaps the user has not yet created any data. The presentation of this empty state depends on the context of the list and the type of data it contains. Be mindful of the journey to rendering an empty state and any possible layout shift along the way.

Presentational

The user may be learning about a feature for the first time, and could benefit from lightweight feature education or onboarding. Use the dedicated Empty State Presentational component in this case, putting emphasis on an action the user can take.

<ComponentPreview name="empty-state-presentational-icon" peekCode wide />

Remember to use active language in presentational empty states. For example: “Create a vector bucket” instead of “No vector buckets found”. The latter is more appropriate in table-based presentations, as described below.

Informational

Or perhaps the list type is data-heavy or does not benefit from additional information. In these cases, the empty state should provide show the initial state in the same presentation as the list when there is data, much like the zero results scenario.

<ComponentPreview name="empty-state-initial-state-informational" peekCode wide />

Keep in mind that empty states will likely appear after a visual loading state. Consider layout shift and button placement during and after the transition.

Zero results

Data-heavy presentations without results should have an empty state that broadly matches the state when there is data. This makes the transition between the two states more seamless.

Table

A Table instance with zero results should display a single row. Dulling the TableHead text color and removing the TableCell hover state can further reinforce the lack of usable data.

<ComponentPreview name="empty-state-zero-items-table" peekCode wide />

Studio contains two pre-built components to handle these cases consistently:

• No Filter Results
• No Search Results

Data Grid

Data Grid and Data Table component patterns typically span the full height and width of a container. A classic example is Users, which (as it sounds) displays a list of the project’s registered users. Any instance with zero results should display a more prominent empty with a clear title, description, and supporting illustration.

<ComponentPreview name="data-grid-empty-state" peekCode wide />

Other Data Grid instances include Cron Jobs and Queues.

Missing route

Users may accidentally navigate to a non-existent dynamic route, such as a non-existent bucket in Storage or a non-existent table in the Table Editor. In these cases, follow the pattern of a centered Admonition as shown below.

<ComponentPreview name="empty-state-missing-route" peekCode wide />

Components

For presentational empty states (initial states with value propositions and actions), use the Empty State Presentational component from ui-patterns. This component provides a consistent structure with support for icons, titles, descriptions, and action buttons.

For other empty state scenarios (zero results, missing routes, etc), custom components may still be appropriate as the context and needs for each placement can differ significantly.