Empty State
FreeA placeholder for a list, table or search that has nothing to show: what is missing, why, and what to do next.
npx wunderui-cli add empty-statePlayground
No projects yet
Projects hold tasks, files and members. Create the first one to get started.
Installation
npx wunderui-cli add empty-stateWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { EmptyState } from "@/components/wunderui/stat-card"Then use it:
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.
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
Content
The title says what is missing. A description says why and what will appear, and an icon gives the message a place to start, in that order.
No invoices yet
No invoices yet
Invoices appear here as soon as the first one is sent.
No invoices yet
Invoices appear here as soon as the first one is sent.
Action
Use one button. A call to action when the list is empty for the first time, a plain button to undo a filter or try again, and a link to lead to help.
No invoices yet
Invoices appear here as soon as the first one is sent.
No invoices yet
Invoices appear here as soon as the first one is sent.
No invoices yet
Invoices appear here as soon as the first one is sent.
No invoices yet
Invoices appear here as soon as the first one is sent.
Behavior and motion
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
The parts of an empty state, numbered in the figure. Only the title is required; the icon, description and action are optional.
No invoices yet
Invoices appear here as soon as the first one is sent.
- 1data-slot="empty-state"
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.
- 2Optional
The icon, drawn in a round 48 px well at 24 px. Pass a Lucide icon.
- 3
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.
- 4Optional
The text under the title: why the place is empty, or what will appear here.
- 5Optional
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.
- Do
For a search without results, name the query and offer a way out: No results for Anders, with a Clear search action.
- Do
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.
- Do
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.
- Do
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
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
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 is a single component with no parts. It takes the props below and no others, so a class name is the only way to style it from outside.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| title required | string | — | One short line on what is missing. Required. |
| 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. |
| action | ReactNode | — | The node below the text: a Button, a row of buttons or a link. |
| variant | "default" | "outline" | "dashed" | "background" | "dashed" | The frame: (default), , without a frame, or with a muted fill. |
| className | string | — |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("empty-state")npx wunderui-cli add empty-stateThe full library index for assistants is at /llms.txt.
Related components
Recent invoicesInvoices issued in the last 30 days Invoice Status Customer Amount INV-2041 Paid WunderUI $24,800.00 INV-2040 Open Halcyon Labs $3,200.00 INV-2039 Overdue Pergola Foods $980.00 INV-2038 Paid Marlow & Finch $12,400.00 Total Sum$41,380.00 Core Elements5 stylesTableRows and columns with 23 ready-made cell types; for sorting and search use Data Table.