Shadcn Empty State Components

Shadcn Empty State Component

The Shadcn Empty State is a React component for the screen users see when there is nothing to show yet: no projects, no search results, no connection or a missing page. A good empty state explains why the area is empty and offers the next step, which turns a dead end into a moment that guides the user forward.

No results, no connection, a 404 page and a maintenance notice each call for a different tone, and the shadcn empty state variants here cover all of them, from a small icon tile with actions to an illustrated Not Found page with search. The component is plain layout markup built with shadcn/ui, React and Tailwind CSS with no primitive library underneath, so it works the same in projects that use Radix UI or Base UI.

What is the Shadcn Empty State Component?

An empty state is a centered block with three layers: a visual (an icon, an illustration or a group of avatars), a short title with a description, and an optional content area for actions such as a button, a search field or a support link. The shadcn/ui Empty component splits these into small composable parts, so you arrange only what the situation needs and keep the spacing consistent across your app.

Use an empty state when a list, table, dashboard or page has no data to display. While data is still loading, show a Skeleton or a Spinner instead, and for an error or warning that sits next to existing content, use an Alert.

Anatomy of the Shadcn Empty State

8 Shadcn Empty State Variants

Each empty state variant listed here is previewed live at the top of this page, together with its source code and install command.

• Icon with actions: A No Projects Yet screen with a folder icon tile and two buttons to create or import a project.
• With avatars: Overlapping avatars above a no designers found message with an inline link and a Clear search button.
• With illustration: A grayscale illustration for an empty cloud storage screen with an Upload Files button, inverted in dark mode.
• 404 with search: An illustrated Not Found page with a search input, a keyboard shortcut hint and a support link.
• Maintenance mode: An illustrated scheduled maintenance message with Check Status and Refresh Page actions side by side.
• Minimal no results: Just a search icon and a No items found title, for small panels and dropdowns.
• Large 404: A text-only Not Found screen with an oversized 404 title and Go back and Contact support buttons side by side.
• No connection: An offline screen with a Wi-Fi off icon tile, a No Internet Connection title and a Try Again action.

How to Install the Shadcn Empty State Component

Set up shadcn/ui in your project if you have not already, then add the Shadcn UI Kit registry to your components.json once:

{
  "registries": {
    "@shadcnuikit": "https://shadcnuikit.com/r/{name}.json"
  }
}

Then install a empty state variant by its name:

npx shadcn@latest add @shadcnuikit/empty1

The same command works with pnpm dlx, yarn dlx and bunx --bun. Each variant has a copy button for every package manager, and the code is added to your project as plain React and Tailwind CSS that you can edit freely.

How to Use the Shadcn Empty State Component

Import the parts from components/ui/empty and render the empty state in place of the list or table when there is no data. Use the icon media variant for a simple icon tile.

import { FolderIcon } from "lucide-react"

import { Button } from "@/components/ui/button"
import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@/components/ui/empty"

export function ProjectList({ projects }: { projects: string[] }) {
  if (projects.length === 0) {
    return (
      <Empty className="border">
        <EmptyHeader>
          <EmptyMedia variant="icon">
            <FolderIcon />
          </EmptyMedia>
          <EmptyTitle>No projects yet</EmptyTitle>
          <EmptyDescription>
            Create your first project to get started.
          </EmptyDescription>
        </EmptyHeader>
        <EmptyContent>
          <Button size="sm">Create project</Button>
        </EmptyContent>
      </Empty>
    )
  }

  return <ul>{/* project rows */}</ul>
}

Why Use the Shadcn Empty State Component

• No dead ends: Every empty screen explains what happened and offers a clear next action.
• Consistent layout: The same spacing and typography for every empty list, search and error page across your app.
• Flexible visuals: Use an icon tile, an illustration, avatars or plain text without changing the structure.
• Lightweight: Plain div elements with Tailwind classes, no client JavaScript and no extra dependencies.
• Theme aware: Muted colors and the icon tile come from your theme variables and follow dark mode.

Common Empty State Use Cases

• First run screens: Empty dashboards, projects or inboxes that invite users to create their first item.
• No search results: Explain that nothing matched and offer to clear the search or filters.
• 404 pages: A friendly Not Found page with a search box and links back to safety.
• Offline and error states: No connection or failed load screens with a retry button.
• Maintenance pages: Tell users the service is temporarily down and where to check its status.
• Empty tables and lists: Replace an empty table body in a data table or file manager.

Customizing the Shadcn Empty State

Every part accepts a className, merged with cn(). Add border to the root for a dashed outline, use flex-row on EmptyContent to put buttons side by side, or enlarge EmptyTitle for a bold 404 headline. Illustrations look consistent in both themes with grayscale and dark:invert, as in the illustrated variants.

<Empty className="border bg-muted/30">
  <EmptyHeader>
    <EmptyTitle className="text-8xl font-semibold">404</EmptyTitle>
    <EmptyDescription>This page does not exist.</EmptyDescription>
  </EmptyHeader>
  <EmptyContent className="flex-row justify-center gap-2">
    <Button size="sm">Go back</Button>
    <Button size="sm" variant="outline">Contact support</Button>
  </EmptyContent>
</Empty>

Empty State Accessibility

EmptyTitle renders a div, so when the empty state is the main content of a page, such as a 404, pass a real heading through your own markup or give the title role="heading" with an aria-level. Decorative illustrations should have an empty alt attribute, as in the examples, so screen readers skip them.

When the empty state replaces results after a search or filter, place it inside an aria-live="polite" region so the change is announced. Action buttons are regular buttons and links, reachable with Tab.

Empty State Best Practices

• Say what is empty and why in plain words; avoid vague titles like Nothing here.
• Offer one primary action, and at most one secondary action next to it.
• Match the tone to the situation: encouraging for first use, calm and helpful for errors.
• Keep illustrations small and neutral so the message and the action stay in focus.
• Do not show an empty state while data is loading; use a Skeleton until the request finishes.
• For no results, show the search term and a way to clear filters.

Components Related to Empty State

Shadcn Empty State FAQ

Looking for something else? Browse all shadcn/ui components or ready-made UI blocks built with them.