Layout/Empty

Empty

Placeholder for empty states in layouts.

Themed

When to Use

Use Empty when you need to:

  • Show a placeholder when a list, table, or content area has no data
  • Guide users to take action after an empty search or filter result
  • Display a friendly 404 or "not found" page with recovery options
  • Communicate that a feature is available but not yet populated
  • Provide onboarding cues for first-time users in a new workspace

When Not to Use

  • Content is loading - use Skeleton for loading placeholders
  • Showing error states with retry - use Alert for error messaging
  • Simple informational messages - use Card with descriptive text
  • Inline empty values in a row - use a dash or placeholder text instead

Default

Empty state with icon, title, description, and action buttons.

No Projects Yet
You haven't created any projects yet. Get started by creating your first project.
Learn More

Outline

Dashed border variant for drop zones or placeholder areas within a layout.

Cloud Storage Empty
Upload files to your cloud storage to access them anywhere.

With Background

Gradient background variant for full-page or section-level empty states.

No Notifications
You're all caught up. New notifications will appear here.

With Avatar

Displays a user avatar in the media slot for person-related empty states.

CN
User Offline
This user is currently offline. You can leave a message to notify them or try again later.

Avatar Group

Multiple overlapping avatars for team or collaboration-related empty states.

CNMLER
No Team Members
Invite your team to collaborate on this project.

With Search

Includes a search input for 404 pages or empty search results with recovery actions.

404 - Not Found
The page you're looking for doesn't exist. Try searching for what you need below.
Need help? Contact support

UX & Design Guidelines

Visual Hierarchy

Lead with a relevant icon or illustration using EmptyMedia, followed by a concise title in EmptyTitle and supporting text in EmptyDescription. Always provide at least one actionable button in EmptyContent so users know what to do next.

Spacing & Layout

The component is centered by default with text-center and items-center. Internal gaps use gap-6 between major sections and gap-2 within the header. Use border border-dashed for placeholder/drop-zone contexts and gradient backgrounds for full-page empty states.

Responsive Behavior

The component uses text-balance for even line wrapping across breakpoints. Padding scales from p-6 on mobile to md:p-12 on larger screens. The max-w-sm constraint on header and content prevents overly wide text on large displays.

Color & Contrast

Titles use text-foreground for maximum readability. Descriptions use text-muted-foreground to establish hierarchy without competing with the title. The icon variant uses bg-muted with text-foreground for sufficient contrast in both light and dark modes.

Accessibility

Keyboard Navigation

  • Tab — Move focus to interactive elements (buttons, links, inputs) inside the empty state
  • Enter or Space — Activate the focused button or link
  • Shift + Tab — Move focus backward through interactive elements

Screen Reader Support

  • Use role="status" on the root Empty for states that update dynamically (e.g., after filtering)
  • Add aria-label to provide context when the empty state meaning is not obvious from its text alone
  • Icons in EmptyMedia are decorative; add aria-hidden="true" to hide them from assistive technology
  • Action buttons should have descriptive labels that make sense out of context (avoid generic "Click here")

Focus Management

When an empty state appears after a user action (e.g., clearing all items), consider programmatically moving focus to the empty state container or its primary action button using ref.focus() so keyboard users are not stranded at a removed element.

Live Regions

For empty states that appear asynchronously (e.g., after a search returns zero results), use aria-live="polite" on the root element so screen readers announce the state change without interrupting the user.

ARIA Attributes

{/* Empty state with role and label for screen readers */}
<Empty role="status" aria-label="No results found">
  <EmptyHeader>
    <EmptyMedia variant="icon" aria-hidden="true">
      <SearchIcon />
    </EmptyMedia>
    <EmptyTitle>No Results</EmptyTitle>
    <EmptyDescription>
      Try adjusting your search or filter criteria.
    </EmptyDescription>
  </EmptyHeader>
  <EmptyContent>
    <Button>Clear Filters</Button>
  </EmptyContent>
</Empty>

{/* Empty state with live region for dynamic updates */}
<Empty role="status" aria-live="polite">
  <EmptyHeader>
    <EmptyTitle>Inbox Empty</EmptyTitle>
    <EmptyDescription>
      New messages will appear here automatically.
    </EmptyDescription>
  </EmptyHeader>
</Empty>

{/* Decorative icons should be hidden from assistive tech */}
<EmptyMedia variant="icon" aria-hidden="true">
  <FolderIcon />
</EmptyMedia>

Related Components

Card

Container with header, content, and footer for structured information display.

Skeleton

Placeholder shimmer used while content is loading, before an empty state is shown.

Separator

Visually or semantically separates content sections around empty states.

Alert

Callout for error or warning messages when empty state is caused by an issue.

API Reference

The Empty component is composed of six sub-components. Each accepts standard HTML div/p attributes in addition to the props listed below.

Empty

PropTypeDefaultDescription
role"status" | "region" | string—ARIA landmark role. Use "status" for dynamic empty states or "region" for static placeholders.
aria-labelstring—Accessible name for the empty state container when context is not obvious.
classNamestring—Additional CSS classes. Use for border, background gradient, or spacing overrides.

EmptyMedia

PropTypeDefaultDescription
variant"default" | "icon""default"Style variant. "icon" adds a muted background container with fixed size; "default" renders media as-is.
aria-hiddenboolean—Set to true for decorative icons that should be ignored by screen readers.
classNamestring—Additional CSS classes for the media container.

EmptyHeader

PropTypeDefaultDescription
classNamestring—Additional CSS classes for the header container (max-w-sm by default).

EmptyTitle

PropTypeDefaultDescription
classNamestring—Additional CSS classes for the title. Renders as text-lg font-medium by default.

EmptyDescription

PropTypeDefaultDescription
classNamestring—Additional CSS classes for the description. Links inside are automatically styled with underline.

EmptyContent

PropTypeDefaultDescription
classNamestring—Additional CSS classes for the actions container (max-w-sm, centered by default).