Empty

Anatomy

import {Empty} from '@staffbase/design';

<Empty.Root>
  <Empty.Media />
  <Empty.Title />
  <Empty.Description />
</Empty.Root>;

Examples

Sizes

API reference

Root

Media

Title

Description

When to use

• For a region that has no content yet, such as an empty list, table, chart, or dashboard card.
• When a search or filter returns no results.
• When content failed to load and the user can recover from it, for example by retrying or refreshing.
• When you can explain why the region is empty and, where possible, what to do next.

When not to use

• Don’t show an Empty state while content is still loading — use Skeleton or Loading Spinner instead.
• Don’t use an Empty state for a page-level message or system status that isn’t tied to a missing content region — use Banner instead.
• Don’t use an Empty state to confirm or block a destructive action — use Alert Dialog instead.
• Don’t use an Empty state to report a validation problem on a single input — use the error message of Field instead.
• Don’t use an Empty state as a promotional or onboarding surface with long-form content — use Card instead.

How to use

Structure

• Compose an empty state as Empty.Root containing an optional Empty.Media, an Empty.Title, an optional Empty.Description, and an optional action.
• Keep the order media, title, description, action so empty states stay predictable across the product.
• Render the empty state in place of the content that is missing, never above or beside it.
• Empty.Root centers its children and is capped at 400px wide; let the surrounding container control vertical placement and padding.

Media

• Media is optional — include an illustration or icon only when it helps users recognize what is missing.
• Use size="lg" (160px) when the empty content spans the full screen, such as a page-level overview.
• Use size="md" (128px, the default) when the empty state fills a large container such as a table, panel, or main content area.
• Use size="xs" (40px) when the empty state sits in one of several smaller regions on a screen, such as a dashboard card.
• Use an illustration at lg and md, and an icon at xs.
• Omit media when space is limited or when a visual wouldn’t improve understanding of the empty state.
• When one screen shows several empty states, omit the media or reuse the same media in all of them to reduce visual noise.

Title

• Always include Empty.Title — it names what is missing and labels the empty state.
• Set as to the heading level that continues the page’s heading order, such as h2 in a main region or h3 inside a section.
• Set as="p" when the surrounding region already has its own heading and another heading would break the outline.

Actions

• Add an action only when there is a next step the user can take, such as creating the first item or retrying a failed load.
• Show a single action; when the user can’t do anything about the empty state, leave it out.
• Match the action label to the next step named in the description, such as Retry for “Try refreshing the page.”
• Use color="neutral" on the action for recovery actions such as Retry, so the empty state doesn’t compete with primary page actions.

Accessibility

• Replace the missing content with the empty state so screen reader users encounter it first in that region.
• Keep the Empty.Title level in sequence with the surrounding headings and don’t skip levels.
• Never rely on Empty.Media to convey meaning — illustrations and icons are hidden from assistive technology.
• Give the action a label that makes sense on its own, without the title and description around it.

Content & UX copy

• Tell users what is missing and why it is missing.
• Tell users what to do next whenever an action is possible.
• Keep copy brief, concise, and clear.
• Add “Yet” to the title when the region is empty because the user hasn’t acted yet, such as “No Posts Yet”.
• Describe where content will appear with “Once you…, they will display here.”, such as “Once you’ve uploaded files, they will display here.”
• Write no-results and no-data titles of four words or fewer in Title Case, with no ending punctuation.
• Write no-results and no-data titles longer than four words that read as a phrase in sentence case, ending with a period.
• Write error titles of three words or fewer in Title Case, with no ending punctuation.
• Write error titles longer than three words that read as a phrase in sentence case, ending with a period, such as “Something went wrong while loading the chart.”
• Never use exclamation points in a title.
• Write every description in sentence case and end it with a period.
• In an error description, say why the error happened when it is known, and what the user can do about it.