Empty State React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Usage

Import EmptyState from @/components/ui/empty-state.

import { FileUp, UserPlus } from "lucide-react"
import { Button } from "@/components/ui/button"
import { EmptyState } from "@/components/ui/empty-state"

export function ClientsEmpty({ onReload }: { onReload: () => Promise<void> }) {
  return (
    <div className="flex flex-col gap-4">
      <EmptyState
        variant="surface"
        title="No clients yet"
        description="Add your first client or import the list from a CSV to get started."
        actions={
          <>
            <Button variant="outline" leftIcon={<FileUp />}>Import CSV</Button>
            <Button leftIcon={<UserPlus />}>Add client</Button>
          </>
        }
      />
      <EmptyState
        preset="error"
        size="sm"
        title="We could not load the invoices"
        description="Check your connection and try again."
        onRetry={onReload}
      />
    </div>
  )
}

Props

• presetdefault "empty"
  "empty" | "no-results" | "error" | "first-run" | "no-permission" | "offline"

  Picks the default icon, tone and copy for the usual reasons: empty (Inbox, neutral), no-results (SearchX, neutral), error (CircleAlert, danger), first-run (Sparkles, brand, with a plus badge), no-permission (Lock, warning), offline (WifiOff, neutral). Every piece stays overridable.

• titledefault ""
  ReactNode

  The heading. Leave empty for the preset's; null hides it.

• descriptiondefault ""
  ReactNode

  One or two sentences under the title; wraps at 36ch (44ch at lg). Leave empty for the preset's; null hides it.

• icon
  ReactNode

  The glyph inside the tile, sized by the empty state. Defaults to the preset's icon; null hides the tile.

• illustration
  ReactNode

  Replaces the tile with an image or an svg, at most 112 / 160 / 192px tall by size. Decorative (aria-hidden).

• badge
  ReactNode

  A small round badge on the tile's corner in the tone's fill. first-run shows a plus; null hides it.

• tonedefault ""
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The tile tint. Empty uses the preset's tone. neutral is a quiet gray tile; the others use the tone's soft fill and text.

• colordefault ""
  string

  Any CSS color for the tile (and the badge); replaces the tone.

• sizedefault "md"
  "sm" | "md" | "lg"

  sm inside a table, list or popover (40px tile, 14px title, 24px padding); md in a panel (48px tile, 15px title, 40px padding); lg for a whole page (64px tile, 18px title, 64px padding, 40px below 640px).

• variantdefault "plain"
  "plain" | "dashed" | "surface"

  plain sits on whatever is behind it; dashed draws a dashed frame (first-run areas, drop zones); surface is a raised panel.

• aligndefault "center"
  "center" | "start"

  start aligns text and actions to the start edge, for cards and sidebars.

• actions
  ReactNode

  Buttons. Put the primary action last in the DOM: it sits at the end of the row and on top when the row stacks.

• onRetry
  () => (void | Promise<unknown>)

  Adds an outline retry button after the actions (meant for the error and offline presets). A returned promise keeps it loading until it settles.

• retryLabeldefault "Try again"
  string

  The retry button's label.

• titleAsdefault "h3"
  "h2" | "h3" | "h4" | "p"

  The title's element, to fit the page's heading outline.

• livedefault false
  boolean

  role="status" with a polite live region, so a screen reader announces the state when it appears. Use it for results that change, like no-results under a search.

• animateddefault true
  boolean

  Tile, text and actions rise in with a short stagger when the state mounts. Server-rendered markup shows the final state; reduced motion fades only. The demo's replay button remounts it.

• presets
  Partial<Record<EmptyStatePreset, Partial<EmptyStatePresetConfig>>>

  Overrides merged over DEFAULT_EMPTY_STATE_PRESETS ({ icon, tone, title, description, badge } per preset). Translate once for the whole app with <UIProvider defaults={{ "empty-state": { presets } }}>.

• children
  ReactNode

  Extra content between the description and the actions: suggestions, a search field, a list of shortcuts.

• classNames
  Partial<Record<"media" | "icon" | "badge" | "title" | "description" | "content" | "actions", string>>

  Extra classes for the inner parts: the tile or illustration, the glyph, the corner badge, the title, the description, the children wrapper, the actions row.

• className
  string

  Extra classes for the root, merged last.

Parts

FAQ

Used in

More React feedback components