Empty

Install

pnpm dlx shadcn@latest add @vegastack/empty

Usage

import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyMedia,
  EmptyTitle,
} from "@/components/ui/empty";
import { Inbox } from "lucide-react";

<Empty variant="dashed">
  <EmptyHeader>
    <EmptyMedia>
      <Inbox />
    </EmptyMedia>
    <EmptyTitle>No messages</EmptyTitle>
    <EmptyDescription>Your inbox is empty.</EmptyDescription>
  </EmptyHeader>
</Empty>;

Anatomy

Empty is a compound component. Compose the parts inside the root:

<Empty variant="dashed" size="md">
  <EmptyHeader>
    <EmptyMedia intent="default">{/* lucide icon */}</EmptyMedia>
    <EmptyTitle>Title</EmptyTitle>
    <EmptyDescription>Supporting description text.</EmptyDescription>
  </EmptyHeader>
  <EmptyContent>{/* action buttons */}</EmptyContent>
</Empty>

• Empty — the centered container (data-slot="empty"). Owns size and variant.
• EmptyMedia — a tinted circular chip around a lucide-react icon (data-slot="empty-media", decorative aria-hidden). Owns the intent tint.
• EmptyTitle — the primary heading (<h3> by default, data-slot="empty-title"). Owns as, so the page picks the heading level.
• EmptyDescription — supporting body text (<p>, data-slot="empty-description").
• EmptyContent — a centered row of call-to-action controls (data-slot="empty-content").

Examples

Sizes

size controls vertical density only — sm (py-8) for empties inside cards, md (py-12) standalone, and lg (py-16) for full-page zero-data screens.

Variants

variant is the one container axis. plain (the default) has no border and no fill, so the block blends into the surrounding layout; dashed draws the classic drop-zone outline; card paints a filled bg-card panel with the one hairline, which reads as a self-contained block on any background. There is no way to ask for a dashed card — that combination had no defined outcome.

Without an icon

EmptyMedia and EmptyContent are both optional. A title-and-description-only empty is a common compact form — for example, a "no filters applied" hint.

Variant × size matrix

The two root axes combine freely. This grid crosses variant (dashed vs. card) with size (sm vs. lg) to show how padding, panel fill, and the dashed outline interact.

Intents

EmptyMedia takes an intent that tints the chip — neutral default, info, or destructive — each mapping to semantic status tokens (bg-X-subtle text-X-text). Use destructive for error/failure empties, info for search/filter empties, and default for plain zero-data states.

Illustration & value tiers

The empty-state system spans eight tiers; two are Wave-2 additions. EmptyIllustration renders one of six built-in monoline drawings (clipboard, bell, search, box, error, not-found) on a faint grid-paper ground — all currentColor, so the error tier is just text-destructive-text on the media slot, no extra asset. EmptyValue is the inline tier: a single faint phrase for a value slot ("No value", "Set a value…").

Playground

Combine the container variant and size with the media chip's variant and intent, then copy the generated JSX.

<Empty>
  <EmptyHeader>
    <EmptyMedia>
      <Inbox />
    </EmptyMedia>
    <EmptyTitle>No messages</EmptyTitle>
    <EmptyDescription>Your inbox is empty.</EmptyDescription>
  </EmptyHeader>
</Empty>

API Reference

Empty

EmptyMedia

EmptyTitle

EmptyDescription

EmptyContent

Accessibility

• The title renders as a real heading (<h3> by default) so assistive technology can navigate to it. Set as to match the page's outline — h2 when the empty state replaces a whole page body, p when the surrounding card already carries the heading.
• The icon chip is decorative (aria-hidden) — meaning is carried by the title and description text, never by the icon or color alone.
• Action controls inside EmptyContent are real buttons/links with their own accessible names and :focus-visible rings.
• The container is non-interactive; keyboard focus order flows through the action controls only.

Do / Don't