EmptyState
What shows where content will be: a title, a line about how to add some, and the actions that do.
import { EmptyState } from "@butteryui/react";Demo
No orders yet
Orders show up here once a customer checks out, or when you add one by hand.
When to use it
Use it for
- A canvas, list or page with nothing in it yet
- After the last item is removed, with a toast offering Undo
- A place files can be dropped (variant="dashed"), inside a DropZone
Not for
- An error: use Callout
- Loading: keep the layout and show skeletons
Examples
Empty canvas
The gift card builder's empty canvas, with the two ways to begin: a primary and a secondary pill.
An empty gift card
Pick one of the shop's designs, or upload a photo of your own.
No design picked yet
Empty list
A list that has nothing in it yet, with no action to take.
No refunds yet
Refunds you give show up here.
Empty panel
A small dashed empty state in a product's photos panel, where the photos will go.
Photos
No photos yet
Add a photo of the bag and one of the beans.
No orders
An app page with nothing in it yet: an icon tile, the way to add some, and where to read more.
Orders
Today
No orders yet
Orders show up here once a customer checks out, or when you add one by hand.
Variants and states
Empty canvas
The title, its line 12px under it, and two pills 24px under the text.
An empty gift card
Pick one of the shop's designs, or upload a photo of your own.
Text only
No refunds yet
Refunds you give show up here.
Sizes
sm for a panel or a table: a 40px tile, the line 8 under the title and the actions 16 under the text. lg for a whole page: a 56px tile, a title-lg heading over body text and the actions 32 under it.
No refunds yet
Refunds you give show up here.
No orders yet
Orders show up here once a customer checks out.
Dashed
variant dashed draws the empty state inside a 2px dashed edge with 16px corners, as a drop target is, padded 24, 32 or 48 by its size.
Add photos of the bag
Drop them here, or pick them from your computer.
Props
EmptyState
| Prop | Type | Default | Description |
|---|---|---|---|
titlerequired | ReactNode | What's missing, such as "No orders yet". | |
description | ReactNode | How to add it, 12px under the title, such as "Orders show up here once a customer checks out." | |
actions | ReactNode | The ways to add it, 24px under the text: a primary and a secondary pill. | |
icon | ComponentType<IconComponentProps> | An icon for what's missing, drawn 20px in a 48px tile 16px above the title, such as Receipt for orders. | |
docs | ReactNode | A link to read more, 16px under the text, such as <ArrowLink href="…">How orders work</. | |
titleAs | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "h2" | What the title renders as. Defaults to "h2". |
size | "sm" | "md" | "lg" | "md" | How much room it takes: "sm" for a panel or a table (a 40px tile, the line 8 under the title and the
actions 16 under the text), "md" (the default), or "lg" for a whole page (a 56px tile, a title-lg
heading over body text, and the actions 32 under it). |
variant | "plain" | "dashed" | "plain" | "plain" (the default), or "dashed": inside a 2px dashed edge with 16px corners, as a drop target is
drawn, padded 24, 32 or 48 by its size. |
It also takes Omit<ComponentPropsWithRef<"div">, "title">.
Accessibility
A heading (h2 unless titleAs says otherwise) with its line, the docs link and the actions as buttons, in reading order. The icon tile is decorative.
It takes no keyboard input of its own.
Motion
It doesn't move.
With reduced motion: Nothing changes.
Layout
It's as wide as its container, everything centered and its text wrapping: an optional 48px icon tile 16 above the title, the line 12 under the title, an optional docs link 16 under the text, then the actions 24 under that, 8 apart, wrapping onto another row when they don't fit. At size sm (a panel or a table) the tile is 40, the line 8 under the title, the tile and docs link 12 from the text and the actions 16; at lg (a whole page) the tile is 56, the heading title-lg over body text, the tile and docs link 20 from the text and the actions 32. The dashed variant draws a 2px dashed edge with 16px corners around it, padded 24, 32 or 48 by size.
Related
See it in the roastery demo's settings. See it in the Halfmoon shop demo. See it in the Deckhand demo.