Empty State

EmptyState gives users context when there is nothing to show and, optionally, a path forward. It renders at the same size as the content it replaces, so the layout does not collapse unexpectedly.

Live demo

Usage

import { EmptyState } from "@beacon/design-system";

// Basic
<EmptyState
  title="No notices yet"
  description="Notices are generated on the first monthly run."
/>

// With action
<EmptyState
  title="No projects"
  description="Add your first lien project to get started."
  action={<button type="button">Add project</button>}
/>

// With icon
<EmptyState
  icon={<FolderIcon aria-hidden />}
  title="No documents"
  description="Upload a document to attach it to this project."
  action={<button type="button">Upload</button>}
/>

Props

Prop	Type	Default	Description
title	ReactNode	—	Primary message. Keep it short and specific (e.g. “No projects”). Required.
description	ReactNode	undefined	Supporting detail or next-step instruction.
icon	ReactNode	undefined	Illustration or icon rendered above the title.
action	ReactNode	undefined	Primary call to action (a button or link).

Design tokens used

Token	Role
--ds-color-content-default	Title text.
--ds-color-content-dim	Description text.
--ds-color-content-muted	Icon color.
--ds-space-md	Internal spacing.

When to use

• A list or table with zero rows.
• A search that returned no results (customize title and description to reflect the query).
• A first-run state before the user has created any data.

Always show EmptyState instead of leaving a blank area. Users need to know the absence of content is intentional and what they can do about it.