EmptyState

The canonical layout for empty lists, no-results, first-run, error, success, and loading surfaces. Drop it anywhere the data could be absent: data tables, search results, dashboards, file lists, inboxes.

EmptyState is two APIs in one: the prop-driven shortcut form for the 80% case, and a compound form (<EmptyState.Icon> / .Illustration / .Title / .Description / .Actions) for full control. When any compound child is detected, the prop-driven shortcuts are silently ignored — the two modes never compete.

Anatomy

┌─────────────────────────────────────────────────────┐
│                       ◯                             │   ← <EmptyState.Icon> / .Illustration
│                                                      │
│                 No users yet                         │   ← <EmptyState.Title> (<h3> by default)
│      Invite your team to collaborate.                │   ← <EmptyState.Description> (<p>)
│                                                      │
│        [Invite teammates]  [Learn more]              │   ← <EmptyState.Actions> (flex row)
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│                       ◯                             │   ← <EmptyState.Icon> / .Illustration
│                                                      │
│                 No users yet                         │   ← <EmptyState.Title> (<h3> by default)
│      Invite your team to collaborate.                │   ← <EmptyState.Description> (<p>)
│                                                      │
│        [Invite teammates]  [Learn more]              │   ← <EmptyState.Actions> (flex row)
└─────────────────────────────────────────────────────┘

Variants

The loading variant auto-injects a <Spinner /> in the icon slot only when neither icon nor illustration is supplied (nor a compound <EmptyState.Icon> child). Pass an explicit icon to override.

Sizes

Action shortcuts

Both primaryAction and secondaryAction accept the same shape:

type ActionShortcut = {
  label: ReactNode;
  onClick?: () => void;
  href?: string;          // when set, renders as <Button asChild><a href=…>
  target?: string;        // anchor target, only meaningful with href
  rel?: string;           // anchor rel,    only meaningful with href
  variant?: 'solid' | 'outline' | 'ghost';   // default: primary='solid', secondary='ghost'
  color?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info' | 'neutral';
  // …all other <Button> props
};

type ActionShortcut = {
  label: ReactNode;
  onClick?: () => void;
  href?: string;          // when set, renders as <Button asChild><a href=…>
  target?: string;        // anchor target, only meaningful with href
  rel?: string;           // anchor rel,    only meaningful with href
  variant?: 'solid' | 'outline' | 'ghost';   // default: primary='solid', secondary='ghost'
  color?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info' | 'neutral';
  // …all other <Button> props
};

When target="_blank" is set without an explicit rel, the component injects rel="noopener noreferrer" automatically.

Examples

Props

<EmptyState />

Subcomponents

All five subparts pull size / variant / align from EmptyStateContext.

Accessibility

• Variant decides the role. default / success → region. error → alert. loading → status + aria-busy="true" + aria-live="polite".
• Title is the accessible name. When prop-driven, the root auto-wires aria-labelledby to the auto-rendered <h3>. Compound mode + custom Title with an explicit id will be picked up too if the consumer passes <EmptyState aria-labelledby={myId}>.
• Description is the accessible description. Same aria-describedby pattern.
• Icon / illustration are decorative. Always aria-hidden="true" so they don't duplicate the title in the AT tree.
• Actions are real buttons. <Button> / <Button asChild><a/> — full keyboard support, focus ring, native semantics.
• href actions are safe by default. target="_blank" without rel injects rel="noopener noreferrer".
• axe-core. Zero violations across variant × size × align, including compound mode and the auto-Spinner loading variant.

Theming

defineTheme({
  components: {
    EmptyState: {
      defaultProps: { size: 'lg', bordered: true },
      styleOverrides: {
        root: 'bg-bg-paper',
        icon: 'shadow-sm',
        title: 'tracking-tight',
        description: 'leading-loose',
        actions: 'gap-3',
      },
    },
  },
});

defineTheme({
  components: {
    EmptyState: {
      defaultProps: { size: 'lg', bordered: true },
      styleOverrides: {
        root: 'bg-bg-paper',
        icon: 'shadow-sm',
        title: 'tracking-tight',
        description: 'leading-loose',
        actions: 'gap-3',
      },
    },
  },
});

Each of the six slots (root / icon / illustration / title / description / actions) is themable independently. defaultProps applies under both the prop-driven and compound APIs.

Integration patterns

DataGrid, FileUpload, and Combobox can consume EmptyState as their default empty / no-results slot content.