EmptyState
Empty states explain why content is unavailable and, when useful, give people a clear next step.
Overview and decision boundary
Use EmptyState when a surface has no content and the user needs context or a next step.
Do not blame users, show technical failures without context, or reuse the same generic copy for every product state.
import { UserPlus } from "@nerio-ui/adapters/icons";import { EmptyState, EmptyStateActions, EmptyStateDescription, EmptyStateHeader, EmptyStateMedia, EmptyStateTitle, Icon,} from "@nerio-ui/ui";import { Button } from "@nerio-ui/ui/client";<EmptyState size="lg"> <EmptyStateMedia aria-hidden="true"> <Icon icon={UserPlus} /> </EmptyStateMedia> <EmptyStateHeader> <EmptyStateTitle>No team members yet</EmptyStateTitle> <EmptyStateDescription> Invite people to collaborate on projects and share updates with the team. </EmptyStateDescription> </EmptyStateHeader> <EmptyStateActions> <Button leadingIcon={UserPlus} size="md">Invite team members</Button> </EmptyStateActions></EmptyState>Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm exec nerio add empty-stateimport { EmptyState, EmptyStateActions, EmptyStateDescription, EmptyStateHeader, EmptyStateTitle } from '@nerio-ui/ui';import { Button } from '@nerio-ui/ui/client';Usage
import { EmptyState, EmptyStateActions, EmptyStateDescription, EmptyStateHeader, EmptyStateTitle } from '@nerio-ui/ui';import { Button } from '@nerio-ui/ui/client';<EmptyState> <EmptyStateHeader> <EmptyStateTitle>No collections</EmptyStateTitle> <EmptyStateDescription>Create one to start organizing work.</EmptyStateDescription> </EmptyStateHeader> <EmptyStateActions> <Button>Create collection</Button> <Button variant="ghost">Learn more</Button> </EmptyStateActions></EmptyState>Variants
| API | Value | Use |
|---|---|---|
size | sm | Compact tables, lists, cards, sidebars, and panels. |
size | md | Standard page sections and large containers. This is the default. |
size | lg | Page-level empty states and first-use onboarding. |
align | center | Centers the content within the available parent surface. This is the default. |
align | start | Aligns content to the start edge for dialogs, sidebars, and narrow panels. |
media variant | icon | Adds a compact neutral icon container sized by the parent EmptyState. |
media variant | illustration | Accepts consumer-owned SVG, image, or custom illustration without a background. |
actions orientation | horizontal | vertical | Wraps actions by default, or stacks them when a vertical action group is clearer. |
Anatomy
| Slot | Purpose |
|---|---|
empty-state | Optional root container that owns size, alignment, and standard HTML/ARIA attributes. |
empty-state-media | Optional icon or illustration container. |
empty-state-header | Optional grouping for the title and description with a readable max width. |
empty-state-title | Optional semantic heading. It renders h3 by default and supports h2 through h6. |
empty-state-description | Optional muted supporting copy rendered as a paragraph. |
empty-state-actions | Optional wrapping group for buttons, links, or other consumer-supplied controls. |
States
| Situation | Announcement and behavior |
|---|---|
| Static empty content | Use no ARIA role by default; the surrounding page context already explains the state. |
| Asynchronous search | Pass role=status or aria-live=polite when a changed query produces no results. |
| Recoverable error | Pass role=alert only when a failure needs immediate announcement, then provide retry when useful. |
| Permission limited | Use neutral media and clear copy; a request-access action belongs in EmptyStateActions. |
Motion
- State changes should use shared motion tokens and preserve reduced-motion behavior.
Accessibility
- EmptyState has no live region or alert role by default; add role=status for asynchronous results and role=alert for an error that needs immediate announcement.
- Keep a clear title, description, and any actions in reading order; decorative media should be aria-hidden.
- Provide no more than two actions unless the surrounding product flow provides a stronger pattern.
Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.
API
| Prop | Values | Purpose |
|---|---|---|
EmptyState.size | sm | md | lg | Controls internal spacing, icon media size, and heading scale. |
EmptyState.align | center | start | Controls content alignment without forcing parent dimensions or chrome. |
EmptyStateMedia.variant | icon | illustration | Chooses compact icon treatment or unframed illustration content. |
EmptyStateTitle.as | h2 | h3 | h4 | h5 | h6 | Selects the heading level that fits the page hierarchy. |
EmptyStateActions.orientation | horizontal | vertical | Controls the action group direction; horizontal actions still wrap. |
All slots | className + native props | Forward refs and standard HTML, data, and ARIA attributes. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | empty-state installs its component, cn utility, and feedback styles. |
Base UI | No interactive primitive is required. |
Registry dependencies | None. |
Package dependencies | clsx, react |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Use EmptyState when a surface has no content and the user needs context or a next step.
Do / do not
Do
Use a short title, explain the most useful next step, and keep the action set to one primary action plus at most one secondary action.
Do not
Reuse generic copy for every state, blame the user, or turn the whole empty-state surface into an interactive control.
Related components
Tokens
| Group | Tokens | Controls |
|---|---|---|
Media | --n-empty-state-mark-size / background / foreground | Icon media dimensions and neutral emphasis. |
Spacing | --n-empty-state-gap | Vertical separation between composed slots. |