Wave 3

Empty State

What a list or page shows before it has content, with the next step. Server-component safe.

Errors loading data: use Alert.
Search with no results: say so inline in the results.

Install

Terminal

pnpm dlx shadcn@latest add @acme/empty-state

Or import from the package: import { EmptyState } from '@acme/react'

Examples

State basic

No projects yet

Projects group invoices, files and people for one client. Create one to get started.

empty-state-basic.tsx

import { FolderPlus } from 'lucide-react'
import { Button } from '@/components/ui/button'
import { EmptyState } from '@/components/ui/empty-state'

export default function EmptyStateBasic() {
  return (
    <EmptyState
      className="w-full max-w-lg"
      icon={<FolderPlus />}
      title="No projects yet"
      description="Projects group invoices, files and people for one client. Create one to get started."
      action={<Button>Create project</Button>}
    />
  )
}

Props

Empty State props
Prop	Type	Default	Description
title (required)	ReactNode	—	What is empty.
description	ReactNode	—	Why, and what to do.
action	ReactNode	—	Usually one primary Button.
icon	ReactNode	—	Decorative icon.
headingLevel	2 \| 3 \| 4	2	Title heading level.

Role: region (section) with a heading
You provide: A heading level that fits the page outline.
Built in: The icon is decorative.
WCAG 2.2 criteria: 1.3.1, 2.4.6

Don’t

Leave an empty state without a next step.

Tokens

color.border
color.muted
color.muted-foreground