Empty state
A resting block that says why a region holds nothing and what the traveller can do about it, with no surface of its own.
No trips yet
Pick where you want to go and the route is drafted for you.
Installation
npx shadcn@latest add @flyingsalmon/empty-stateUsage
import { Button } from '@/components/ui/button'
import {
EmptyState,
EmptyStateActions,
EmptyStateDescription,
EmptyStateTitle,
} from '@/components/ui/empty-state'
export function EmptyStateUsage() {
return (
<EmptyState>
<EmptyStateTitle>No trips yet</EmptyStateTitle>
<EmptyStateDescription>
Pick where you want to go and the route is drafted for you.
</EmptyStateDescription>
<EmptyStateActions>
<Button>Plan a trip</Button>
</EmptyStateActions>
</EmptyState>
)
}Examples
Icon art
The icon holds any node in a muted circle. Use it where a sticker would be too much, such as a small block beside other content.
No travellers yet
Invite the people coming to Lisbon and they can vote on the plan.
Two actions
One or two buttons, primary first. On narrow widths they stack in the same order, so the primary stays on top.
No places saved yet
Save places you like and they wait here until you pick a day.
No action
An empty state with no action is normal. This card has nothing to show until the traveller approves the route elsewhere on the page, so it explains and stops. Wrapping the block in a card is how you give it a boundary.
Activities come after the route
Approve the route and the days fill with activities.
Small with a sticker
Small is for a block inside a surface that already carries heading weight, and the sticker shrinks with it. Pass as on the title for an H3 inside a section.
No packing list yet
Add what you are bringing and travellers can claim the shared items.
An expired link
A dead share link is an empty state and not an error: the traveller landed on a page with nothing in it, and did not act and fail.
This trip link has expired
The owner stopped sharing it, or the trip was deleted.
Guidelines
When to use
- When a page, a list, or a card is legitimately empty: no trips yet, no places saved, nobody invited.
- When a link leads to a page with nothing in it, such as an expired share link.
When not to use
- Use Skeleton when a region is still fetching. The placeholder holds the shape of what is coming.
- Use Error state when a region’s content failed to arrive. That is a failure, and it is announced.
Do and don’t
- DoTitle the block with a plain statement or a short question, and say in the description what the traveller can do next.A resting state with no next step leaves the traveller to guess whether something broke.
- DoLead with one filled action that starts something. A second, outline action may lead out.One filled button is an obvious next step, and the outline beside it tells the traveller which button takes them back.
- DoGive a friendly empty a sticker, and a dead end, such as a trip that does not exist, an icon.The sticker invites the traveller to begin. The icon says plainly that there is nothing here to begin.
- DoKeep a block inside a card quieter than one that fills a page.The card already carries the heading weight, so the block inside it steps down.
- Don’tUse an empty state while content is loading.A skeleton holds the shape of what is coming. The one exception is long work that runs in the background with nothing to draw yet: there, an empty state that says the traveller is free to leave tells the truth.
- Don’tFrame the block itself. Place it in a card when it needs a boundary.On a page it is the page’s own message, and in a card it is the card’s. A frame of its own would compete with both.
- Don’tLet the art outweigh the title. The sticker or icon is never bigger than the title it sits above, so keep its default size.Words lead. A picture larger than its title becomes the message, and the title shrinks to a caption beneath it.
Accessibility
| Key | Description |
|---|---|
| Tab | Reaches the action buttons in order. Nothing else in the block takes focus. |
The block is a region labelled by its title, so a screen reader user can find it. It has no live region: a resting state must not announce itself on every render. The title is a second-level heading by default; pass as for the level the surrounding document needs, such as a third-level heading inside a card.
A sticker is one image named by its label, which describes the picture and does not repeat the title. The icon is hidden from assistive technology.
API
EmptyState
Renders a section labelled by its title and takes every <section> attribute. Compose it from EmptyStateSticker or EmptyStateIcon, EmptyStateTitle, EmptyStateDescription, and EmptyStateActions.
| Prop | Type | Default | Description |
|---|---|---|---|
| size | EmptyStateSize | EmptyStateSize.Default | Default for a page, Small for a block inside a card. The block paints no border or background of its own. |
EmptyStateTitle
Labels the region, through your own id when you pass one. Give every empty state a title: without one the section has no name.
| Prop | Type | Default | Description |
|---|---|---|---|
| as | EmptyStateTitleElement | EmptyStateTitleElement.H2 | H2 or H3, to fit the heading outline of the page. |
EmptyStateSticker
Takes the props of a Sticker and sizes and tilts it for the block.
| Prop | Type | Default | Description |
|---|---|---|---|
| art | StickerArt | Required | The drawing. |
| label | string | Required | What the picture shows, for a screen reader. |
| roleClassNames | StickerRoleClassNames | Required | The colour classes for each role in the art. |
| popIn | boolean | true | Pops the sticker in as it scrolls into view. |
EmptyStateIcon, EmptyStateDescription, and EmptyStateActions take only their element’s props; the description and actions types are EmptyStateDescriptionProps and EmptyStateActionsProps.