Empty

Installation

The components are exported from @by/experience-system. Add the package with your package manager:

pnpm add @by/experience-system

In this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.

Composition

Use the following composition to build an Empty state:

Empty
├── EmptyHeader
│   ├── EmptyMedia (optional)
│   ├── EmptyTitle
│   └── EmptyDescription
└── EmptyContent (optional)

Use Empty when there is nothing to show yet, when an operation failed, or when a long process is in progress. Icons come from @by/icons. For product copy and layout guidance, see the Luminate UX design guidelines for Empty State.

Usage

import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from '@by/experience-system';

Empty and its parts are client components ('use client'). Use them inside a Client Component or a dynamic import when using the Next.js App Router.

<Empty>
  <EmptyHeader>
    <EmptyMedia variant="icon">{/* icon */}</EmptyMedia>
    <EmptyTitle>No results</EmptyTitle>
    <EmptyDescription>Try adjusting filters or search.</EmptyDescription>
  </EmptyHeader>
  <EmptyContent>{/* actions */}</EmptyContent>
</Empty>

Examples

The live preview at the top of this page uses empty-usage.

Informative

The Empty component could be used in cases when the page is empty because of missing initial configuration and some actions are required from the user. In such cases describe why the screen is empty and what is expected from the user to continue. Append it with most expected actions in EmptyContent section. Read more about informative empty states on the Informative/Onboarding states guidelines page.

Error

Use the same composition for failure states: warning icon, error message, explanation on what is happened and how users can go further. Append with recovery actions, and a troubleshooting link when it is required. In case of use as a page-level error the icon could be emphasized with appropriate color: use fill-error-alpha-8! for the nested icon component. For use in a card such visual emphasis is usually not required. More explanation could be read on Error states guidelines page.

Loading

For loading state there is no need to use any icon. Add Progress indicator after a title for short-time loading, and list of ongoing and performed activities inside EmptyContent for long-running processes or setup flows. Read more about usage and best practices on the Loading states guidelines page.

API Reference

Subsection titles name the exports from @by/experience-system. These parts are plain layout components (not Radix primitives).

Empty

Root container (div). Centers content; supports @container/empty for responsive tweaks.

Also accepts standard div attributes.

EmptyHeader

Groups media, title, and description in a column.

Also accepts standard div attributes.

EmptyMedia

Slot for an icon or illustration.

Also accepts standard div attributes.

EmptyTitle

Primary heading.

Also accepts standard div attributes.

EmptyDescription

Supporting text; links pick up underline styles.

Also accepts standard div attributes (renders a div with link-oriented typography).

EmptyContent

Optional region below the header for buttons, lists, or progress.

Also accepts standard div attributes.

Accessibility

• Mark decorative icons with aria-hidden when the title or description already conveys meaning.
• Keep heading and body text in logical order (EmptyTitle before EmptyDescription).
• For loading patterns, expose status to assistive technology (for example aria-busy on a parent region) when appropriate.

Source in the repo: packages/experience-system/src/components/Empty/Empty.tsx. Agent-oriented usage notes: packages/experience-system/src/components/Empty/Empty_instructions.md.