Skip to content
flyingsalmon

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-state

Usage

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.

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

  • Do
    Title 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.
  • Do
    Lead 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.
  • Do
    Give 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.
  • Do
    Keep 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’t
    Use 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’t
    Frame 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’t
    Let 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

KeyDescription
TabReaches 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.

PropTypeDefaultDescription
sizeEmptyStateSizeEmptyStateSize.DefaultDefault 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.

PropTypeDefaultDescription
asEmptyStateTitleElementEmptyStateTitleElement.H2H2 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.

PropTypeDefaultDescription
artStickerArtRequiredThe drawing.
labelstringRequiredWhat the picture shows, for a screen reader.
roleClassNamesStickerRoleClassNamesRequiredThe colour classes for each role in the art.
popInbooleantruePops 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.

  • Error state

    The same block for content that failed to arrive.
  • Skeleton

    What a region shows while its content is on the way.
  • Card

    Gives the block a boundary among other regions.
  • Button

    The actions the block offers.