Empty State

When to use

Reach for EmptyState anywhere a surface can render nothing: an empty table/list, a no-results search, a failed fetch, an offline banner, a permission wall, or first-run onboarding. The host decides whenit's empty and supplies copy + handlers;EmptyState only renders the designed answer — icon or illustration, title, description, up to two actions, and an optional footer hint. Omit action/secondaryAction for a read-only variant — the buttons simply don't render.

Host example — search-empty inside a data table

import { EmptyState } from "@/components/empty-state";

export function ProjectsTable({ rows, filters, onClearFilters }) {
  if (rows.length === 0 && filters.active) {
    return (
      <EmptyState
        variant="search"
        size="sm"
        title={`No results for "${filters.query}"`}
        description="Try a different term or clear the active filters."
        action={{ label: "Clear filters", onClick: onClearFilters }}
      />
    );
  }

  return <Table rows={rows} />;
}

Variants

Six semantic tones, each with its own default lucide icon — override with icon, or replace the tile entirely with media (an illustration slot; when set, the icon and its halo are omitted).

• default — no data yet (Inbox).
• search — no results for a filter/query (SearchX); pairs with a "Clear filters" action.
• error — something failed (TriangleAlert); pairs with a "Retry" action.
• offline — no connection (WifiOff).
• permission — locked content (Lock).
• first-use — onboarding tone (Sparkles), decorative spinning dashed ring around the tile.

Actions

action / secondaryAction accept either an object — { label, onClick?, href?, disabled? } — rendered as a real Button (or a plain <a> styled via buttonVariants when href is set), or any ReactNode for full control over the rendered element.

Sizes

sm for inline/card-level empties, md for a section, lg for a full-page state. Controls type scale, icon-tile scale, and vertical padding.

Frame

frame="dashed" adds a dropzone-style dashed border; frame="card" raises the root onto a bg-card surface. Default "none"renders bare (for slotting into a table body or an already-framed container). A real drag-and-drop dropzone is a separate future component — don't wire drop handlers onto frame="dashed" alone.

Accessibility

• Title renders a real heading (headingLevel, default 3) so empty states participate in the page outline.
• role="status" aria-live="polite" is applied only for the transient variants — search, error, offline — where content changed after a user action. Static walls (permission, first-use) stay plain landmarks; announcing them on mount would be noise.
• The icon tile, bloom, and decorative ring are aria-hidden. Actions are real, keyboard-reachable buttons/links.
• Entrance animation uses motion-safe: variants — no motion for prefers-reduced-motion users, or when animated={false}.