Empty state

• Type: Component (data)
• Access: Free, open source
• Page: https://ui.xzero.co.uk/components/empty-state
• Markdown: https://ui.xzero.co.uk/components/empty-state/markdown
• Registry item: https://mcp.xzero.co.uk/r/empty-state.json
• Source file: registry/components/empty-state/empty-state.tsx
• Dependencies: motion, lucide-react
• Keywords: data, guidance, react empty state, no results, empty list placeholder, zero state, blank slate, first run empty view

When to use

• Empty lists, zero search results, and first-run views.
• A view that should morph between states, such as empty and success, by changing props.

When not to use

• Use skeleton while data is still loading.
• Use alert for errors inside a page that still has content.
• Use onboarding-checklist when first-run needs several steps.

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui/empty-state

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { Search } from "lucide-react";
import { Button } from "@/components/xzero/button/button";
import { EmptyState } from "@/components/xzero/empty-state/empty-state";

export function NoResults({ onClear }: { onClear: () => void }) {
  return (
    <EmptyState
      icon={<Search size={24} />}
      title="No matches"
      description="Try a shorter search or clear the filters."
      action={<Button variant="secondary" onClick={onClear}>Clear filters</Button>}
    />
  );
}

API reference

EmptyState

A centered icon, title, description, and optional action for empty views.

Prop	Type	Default	Description
title (required)	string	–	Headline. A new title rises in while the old one leaves.
description (required)	string	–	One or two sentences on why it is empty and what to do.
action	ReactNode	–	Call to action, usually a button.
icon	ReactNode	<Folder />	Leading icon. A different icon component crossfades in.
className	string	–	Class for the root section.
label	string	–	Accessible name for the section region.

Accessibility

• Renders a section with an h3 title; pass label to name the region.
• The icon is aria-hidden.
• Outgoing copy is hidden from assistive tech while it fades.

Motion

• Changing title or description rolls the copy in place while the block height springs to fit.
• A new icon pops in with a short blur.
• Reduced motion swaps copy with a fade and snaps height; the icon's idle animation stops.

Responsive behavior

• Padding scales with the viewport between fixed bounds, and the description caps at 18rem so lines stay short.
• Actions wrap and center, so two buttons stack on narrow screens.

Performance

• One ResizeObserver drives the height spring; the icon's idle animation is CSS and stops under reduced motion.

Notes for AI

• Use for empty lists, zero search results, and first-run views. Use skeleton while data is loading.
• Keep it mounted and change its props to morph between states such as empty and success.

Related

• Skeleton: Reserve space while content is still loading.
• Alert: A persistent message that helps people recover or continue.
• Onboarding checklist: Guide a new workspace through setup, one step at a time.
• Sortable data table: Compare structured records with sortable columns.

Also in cards

• Card: A contained group of related content and actions.
• Metric card: A compact summary for a number that needs context.
• Metric ticker: A strip of live KPIs that roll to new values digit by digit and flash their change; rest on one to pause the strip and open its recent trend as a sparkline.

Guidance for AI tools

Empty state: A useful next step when there is nothing to show yet. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt