React EmptyState component

Preview

<EmptyState>
  <EmptyState.Icon><FolderIcon /></EmptyState.Icon>
  <EmptyState.Title>No projects yet</EmptyState.Title>
  <EmptyState.Description>Get started by creating your first project.</EmptyState.Description>
  <EmptyState.Actions>
    <Button>Create Project</Button>

Usage

Use when

Lists, tables, or search results with nothing to show
First-run screens before any content exists
Filtered views that matched nothing

Avoid when

Content still loading (use Skeleton)
Failures that need a retry (use Alert)
Transient confirmations (use Toast)

Implementation notes

Say why the area is empty, not just that it is
Give one clear action out of the state; two at most, primary first
Match the icon to the cause: search, inbox, folder
Use size="sm" inside a panel, card or table body and the default md for a page region
The state draws no frame of its own; it sits inside whatever already frames the region
Content is start-aligned with the copy around it

Installation

pnpm add @usefragments/ui

Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Anatomy

Import EmptyState once, then compose its parts with dot notation.

EmptyState.Icon
EmptyState.Title
EmptyState.Description
EmptyState.Actions

First-run state: nothing exists yet, so offer the create action.

<EmptyState>
  <EmptyState.Icon><FolderIcon /></EmptyState.Icon>
  <EmptyState.Title>No projects yet</EmptyState.Title>
  <EmptyState.Description>Get started by creating your first project.</EmptyState.Description>
  <EmptyState.Actions>
    <Button>Create Project</Button>
  </EmptyState.Actions>
</EmptyState>

Examples

No Results

A filter or query matched nothing — offer a way back.

<EmptyState>
  <EmptyState.Icon><SearchIcon /></EmptyState.Icon>
  <EmptyState.Title>No results found</EmptyState.Title>
  <EmptyState.Description>Try adjusting your search terms or filters.</EmptyState.Description>
  <EmptyState.Actions>
    <Button variant="soft">Clear Filters</Button>

With Secondary Action

One primary action plus a quieter alternative.

<EmptyState>
  <EmptyState.Icon><InboxIcon /></EmptyState.Icon>
  <EmptyState.Title>Inbox is empty</EmptyState.Title>
  <EmptyState.Description>You have no new messages.</EmptyState.Description>
  <EmptyState.Actions>
    <Button>Compose Message</Button>

Small

Compact padding for a panel or table body; no icon, no action.

<EmptyState size="sm">
  <EmptyState.Title>No items</EmptyState.Title>
  <EmptyState.Description>Add items to see them here.</EmptyState.Description>
</EmptyState>

API reference

Component props
Prop	Type	Default	Description
`Actions.children`Required	`React.ReactNode`	Not set	—
`children`Required	`React.ReactNode`	Not set	EmptyState content - use EmptyState.Icon, EmptyState.Title, EmptyState.Description, EmptyState.Actions sub-components
`Description.children`Required	`React.ReactNode`	Not set	—
`Icon.children`Required	`React.ReactNode`	Not set	—
`size`	`"sm" \| "md" \| undefinedsmmd`	`md`	Padding only: sm for a panel or table body, md for a page region. Type and icon never change with size.
`Title.as`	`"h2" \| "h3" \| "h4" \| "p" \| undefinedh2h3h4p`	Not set	Heading level follows the surrounding outline: `h2` for a page-level state, `h3` under a section heading. Defaults to `h3`.
`Title.children`Required	`React.ReactNode`	Not set	—

Accessibility

EmptyState.Title renders a heading (h3 by default); set as to match the outline
EmptyState.Icon is decorative and hidden from assistive tech
Action buttons follow button accessibility guidelines

AlertalternativeUse Alert for error states with retry
ProgressalternativeUse Progress/Spinner for loading states

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.