# Empty State

Placeholder shown when a list or search has no results.

- Category: Core Elements
- Page: https://wunderui.com/components/empty-state
- Tier: Free

## Install

```bash
npx wunderui-cli add empty-state
```

## Import

```tsx
import { EmptyState } from "@/components/wunderui/stat-card"
```

## Minimal usage

Then use it:

```tsx
import { Button } from "@/components/ui/button"
import { EmptyState } from "@/components/ui/empty-state"
import { FileText } from "lucide-react"

export function NoInvoices() {
  return (
    <EmptyState
      icon={<FileText />}
      title="No invoices yet"
      description="Invoices appear here as soon as the first one is sent."
      action={<Button>New invoice</Button>}
    />
  )
}
```

Expected result: You see a dashed frame with a round icon, the title No invoices yet, a line of text and a New invoice button, all centred.

## Usage

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

export function Example() {
  return (
    <EmptyState
      icon={<FolderPlus />}
      title="No projects yet"
      description="Projects hold tasks, files and members. Create the first one to get started."
      action={<Button>New project</Button>}
    />
  )
}
```

## When to use

### Use Empty State for

- A list, table or search that has nothing to show, for the first time or after a filter
- A region that failed to load, or that the person may not open, with a way on

### Use something else

- [Skeleton](https://wunderui.com/components/skeleton) for content that is still loading
- [Alert](https://wunderui.com/components/alert) for an error or a notice next to content that is still there
- [Toast](https://wunderui.com/components/toast) for a short message that something happened and needs no action

## Behavior

What the empty state does with content, the page and motion.

- **Not a region:** EmptyState is a plain div with no role, and its title is a paragraph. Put it inside the empty section, and wrap it in a status region when the result changes while someone types.
- **Frame:** Dashed draws a dashed 1 px border with a 16 px radius, outline the same with a solid border, default no frame at all, and background a muted fill with a 24 px radius.
- **Size:** The empty state fills the width of its container, centres its content and keeps 40 px of padding on every side. Give it a container with a width, such as a card or a column.
- **Action:** The action sits 12 px below the text and can be any node. Buttons in it keep their own focus ring and keyboard behaviour.
- **Motion and reduced motion:** The empty state has no motion of its own. If you animate the swap, use the base duration and entrance curve on opacity and transform, with a reduced motion fallback.

## Anatomy

- `EmptyState`: A centred block of icon, title, description and action, with 40 px of padding. Four frames are available: dashed (the default), outline, none, or a muted background fill.
- `Icon`: The icon, drawn in a round 48 px well at 24 px. Pass a Lucide icon.
- `Title`: One short line on what is missing, such as No invoices yet. It renders as a paragraph, not a heading, so it does not change the outline of the page.
- `Description`: The text under the title: why the place is empty, or what will appear here.
- `Action`: Below the text, usually one Button that fills the empty place or undoes the filter. It takes any node, also a row of two buttons or a link.

## Best practices

### Do

- Say what is missing, why and what to do next, then offer one action: No invoices yet, Invoices appear here as soon as the first one is sent, and New invoice.
- For a search without results, name the query and offer a way out: No results for Anders, with a Clear search action.
- For a failure, say what failed and offer the retry as the action: Couldn't load invoices with Try again. Show the pending state on the button while it runs.
- Use the frameless look inside a card or panel that already has a border, and the dashed default where the empty state stands on the page.
- Wrap an empty state that appears after typing in a status region, so a screen reader announces the change.

### Don't

- Don't show a bare No results line. Without a reason and a next step, an empty place looks broken and leaves people stuck.
- Don't use it while data is still loading. A Skeleton shows that something is on its way; an empty state says that nothing is.
- Don't offer two equal calls to action. One primary button, with at most a plain secondary one or a link to help.

## API reference

### EmptyState

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | string |  | One short line on what is missing. Required. |
| action | ReactNode |  | The node below the text: a Button, a row of buttons or a link. |
| className | string |  |  |
| description | string |  | Why the place is empty or what will appear here, in one or two sentences. |
| icon | ReactNode |  | A Lucide icon, drawn in a round 48 px well above the title. |
| variant | "default" \| "outline" \| "dashed" \| "background" | "dashed" | The frame: `dashed` (default), `outline`, `default` without a frame, or `background` with a muted fill. |

## Examples

### Content: title, description and icon

```tsx
import { EmptyState } from "@/components/ui/empty-state"
import { FileText } from "lucide-react"

export function Example() {
  return (
    <EmptyState
      icon={<FileText />}
      title="No invoices yet"
      description="Invoices appear here as soon as the first one is sent."
    />
  )
}
```

### Action: none, a button, two buttons or a link

```tsx
import { Button } from "@/components/ui/button"
import { EmptyState } from "@/components/ui/empty-state"
import { FileText } from "lucide-react"

export function Example() {
  return (
    <EmptyState
      icon={<FileText />}
      title="No invoices yet"
      description="Invoices appear here as soon as the first one is sent."
      action={<Button>New invoice</Button>}
    />
  )
}
```

## In context

### No results after a search

The message names the query and Clear search brings the list back. The empty state sits in a status region, so a screen reader announces the change while typing.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { EmptyState } from "@/components/ui/empty-state"
import { Input } from "@/components/ui/input"
import { SearchX } from "lucide-react"

export function SearchPeople() {
  const [query, setQuery] = useState("Anders")
  const people = ["Nora Lindgren", "Daniel Okafor", "Priya Raman", "Tomás Ferreira", "Maya Kessler"]
  const matches = people.filter((name) => name.toLowerCase().includes(query.trim().toLowerCase()))

  return (
    <div className="flex flex-col gap-3">
      <Input aria-label="Search people" placeholder="Search people" value={query} onChange={(event) => setQuery(event.target.value)} />
      <p role="status" className="sr-only">
        {matches.length === 0 ? "No results" : `${matches.length} ${matches.length === 1 ? "result" : "results"}`}
      </p>
      {matches.length > 0 ? (
        <ul className="divide-y divide-border rounded-xl border border-border">
          {matches.map((name) => (
            <li key={name} className="px-4 py-3 text-sm text-foreground">
              {name}
            </li>
          ))}
        </ul>
      ) : (
        <EmptyState
          variant="outline"
          icon={<SearchX />}
          title={`No results for “${query.trim()}”`}
          description="Check the spelling or try another word."
          action={
            <Button variant="plain" onClick={() => setQuery("")}>
              Clear search
            </Button>
          }
        />
      )}
    </div>
  )
}
```

### First use of a list

Until the first project exists, the list is an empty state with the one action that fills it. Once there is a project, the empty state is gone.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { EmptyState } from "@/components/ui/empty-state"
import { FolderPlus } from "lucide-react"

export function Projects() {
  const names = ["Q4 roadmap", "Pricing experiment", "Onboarding revamp"]
  const [count, setCount] = useState(0)

  return (
    <div className="rounded-xl border border-border">
      <div className="flex items-center justify-between border-b border-border px-4 py-3">
        <span className="text-sm font-semibold text-foreground">Projects</span>
        {count > 0 && count < names.length && (
          <Button variant="plain" onClick={() => setCount(count + 1)}>
            New project
          </Button>
        )}
      </div>
      {count === 0 ? (
        <EmptyState
          variant="default"
          icon={<FolderPlus />}
          title="No projects yet"
          description="Projects hold tasks, files and members. Create the first one to get started."
          action={<Button onClick={() => setCount(1)}>New project</Button>}
        />
      ) : (
        <ul className="divide-y divide-border">
          {names.slice(0, count).map((name) => (
            <li key={name} className="px-4 py-3 text-sm text-foreground">
              {name}
            </li>
          ))}
        </ul>
      )}
    </div>
  )
}
```

### A list that failed to load

The message says what failed and Try again repeats the request. The button shows its pending state while it runs, and the list replaces the empty state when it arrives.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { EmptyState } from "@/components/ui/empty-state"
import { TriangleAlert } from "lucide-react"

export function Invoices() {
  const [status, setStatus] = useState<"error" | "loading" | "loaded">("error")

  const retry = () => {
    setStatus("loading")
    // Stand-in for the request.
    setTimeout(() => setStatus("loaded"), 1200)
  }

  return (
    <div className="rounded-xl border border-border">
      <div className="border-b border-border px-4 py-3 text-sm font-semibold text-foreground">Invoices</div>
      {status === "loaded" ? (
        <ul className="divide-y divide-border">
          <li className="flex justify-between px-4 py-3 text-sm text-foreground">
            <span>INV-1042</span>
            <span>$1,842.00</span>
          </li>
          <li className="flex justify-between px-4 py-3 text-sm text-foreground">
            <span>INV-1041</span>
            <span>$69.98</span>
          </li>
        </ul>
      ) : (
        <EmptyState
          variant="default"
          icon={<TriangleAlert />}
          title="Couldn't load invoices"
          description="Check your connection and try again."
          action={
            <Button variant="plain" pending={status === "loading"} onClick={retry}>
              Try again
            </Button>
          }
        />
      )}
    </div>
  )
}
```

## For AI agents

`get_component("empty-state")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
