Empty states

• Type: Block

• Page: https://ui.xzero.co.uk/components/blocks/empty-states

• Markdown: https://ui.xzero.co.uk/components/blocks/empty-states/markdown

• Access: Free, open source

• Registry id: empty-states

• Source file: registry/blocks/empty-states/empty-states.tsx

• Keywords: react empty state, empty state illustration, no results state, offline state, 404 page illustration, inbox zero, morphing svg illustration

Use this for no results, offline, inbox zero and missing page moments. Wire each action to your real filter reset, retry, refresh or search; the preview simulates them locally.

When to use

• A reference for no results, offline, inbox zero, and 404 moments with one shared illustration style.
• Extracting one scene as a richer empty state for a key screen.

When not to use

• Use empty-state for a simple empty state with an icon, text, and action.
• Use onboarding-illustration for first-run screens that teach the product.
• Use skeleton while content is still loading.

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-states

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 { EmptyStates } from "@/components/xzero/blocks/empty-states/empty-states";

export default function EmptyGallery() {
  return (
    <main>
      <EmptyStates />
    </main>
  );
}

API reference

EmptyStates

Four empty states (no results, offline, inbox zero, missing page) in one illustration that morphs between scenes via tabs, each with a simulated action. Scene copy is in empty-states.tsx and shapes in empty-states-art.ts.

No props.

Keyboard interactions

Keys	Action
Left / Right	Move between scene tabs (wraps around).
Home / End	Jump to the first or last scene.

Accessibility

• Scenes use role="tablist", "tab" and "tabpanel" with aria-selected and aria-controls.
• The illustration is a role="img" labelled by the scene; a polite live region reports action results.

Motion

• Each shape morphs its path to the next scene with slight per-shape delays, and the tab indicator glides with a layoutId.
• Reduced motion swaps scenes with a short fade and no morph.

Responsive behavior

• The block is a container query root; from a 560px container the title steps up a size.
• Pointer parallax only turns on for hover-capable fine pointers, so touch devices get a still illustration.

Performance

• Shape morphs run on a small requestAnimationFrame loop that stops as soon as every shape settles.
• A ResizeObserver springs the copy height when scenes change.

Notes for AI

• Use as a reference for no results, offline, inbox zero or 404 moments; usually you extract one scene rather than ship the tabbed gallery.
• Actions (clear filters, retry, refresh, search) are simulated; wire them to your real handlers.
• For a single simple empty state, prefer the empty-state component.

Related

• Empty state: A useful next step when there is nothing to show yet.
• Onboarding illustration: A compact onboarding card whose line illustration morphs from folder to files, team, and badge.
• Tabs: Switch between related content in the same context.

Guidance for AI tools

Blocks are complete, self-contained screens with sample data. Replace the sample data and connect the callbacks described above. 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