EmptyState

A quiet placeholder that explains missing content and offers an appropriate next step.

Use EmptyState when a collection has no data, no filtered results, or no content yet. Its parent owns the surrounding surface.

No results match your filters

Try removing a filter to see more results.

No filtered results

Installation

$npx shadcn@latest add @patchui/empty-state

The copied source is available in the registry JSON. The canonical implementation lives in packages/react/src/components/empty-state.tsx.

Usage

<EmptyState
  title="No results match your filters"
  description="Try removing a filter to see more results."
  icon={<MagnifyingGlassMinus />}
  action={<Button variant="secondary">Clear Filters</Button>}
/>

Explain why content is absent, then offer the most direct recovery or creation action. Do not restate the title in the description.

Examples

First-use state

For an empty collection, describe the value of adding the first item and provide one clear creation action.

No projects yet

Create a project to organize files and invite collaborators.

First-use state

API reference

Prop	Type	Default	Description
title	ReactNode	-	Names the empty condition.
description	ReactNode	-	Explains the condition or the next useful step.
icon	ReactNode	-	Adds a muted decorative icon above the title.
action	ReactNode	-	Adds the primary recovery or creation action.
children	ReactNode	-	Adds optional supporting content below the primary action.

Content guidance

Describe the state specifically, such as No results match your filters or No projects yet.
Keep the description to one or two short sentences that add information.
Prefer one primary action. Use children only for genuinely useful supporting content or a secondary link.
Match the action to the state, such as Clear Filters, Create Project, or Browse Templates.

Accessibility

EmptyState renders a heading and description but does not add a landmark or live region automatically.
When filtering updates the empty state asynchronously, place the changing results region in aria-live="polite".
The icon is decorative and hidden from assistive technology. Do not encode unique information in it.
Buttons and links supplied through action or children retain their own semantics and accessible names.