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.
No results found
We could not find anything matching “quarterly roadmap”. Try a broader search or clear the active filters.
1import{Search}from"@nerio-ui/adapters/icons";2import{3EmptyState,4EmptyStateActions,5EmptyStateDescription,6EmptyStateHeader,7EmptyStateMedia,8EmptyStateTitle,9Icon,10}from"@nerio-ui/ui";11import{Button}from"@nerio-ui/ui/client";1213<EmptyStatesize="lg">14<EmptyStateMediaaria-hidden="true">15<Iconicon={Search}/>16</EmptyStateMedia>17<EmptyStateHeader>18<EmptyStateTitle>No results found</EmptyStateTitle>19<EmptyStateDescription>20Try a different search or clear the active filters.21</EmptyStateDescription>22</EmptyStateHeader>23<EmptyStateActions>24<ButtonleadingIcon={Search}>Search again</Button>25<Buttonvariant="ghost">Clear filters</Button>26</EmptyStateActions>27</EmptyState>
Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
1import{EmptyState,EmptyStateActions,EmptyStateDescription,EmptyStateHeader,EmptyStateTitle}from'@nerio-ui/ui';2import{Button}from'@nerio-ui/ui/client';34<EmptyState>5<EmptyStateHeader>6<EmptyStateTitle>No collections</EmptyStateTitle>7<EmptyStateDescription>Create one to start organizing work.</EmptyStateDescription>8</EmptyStateHeader>9<EmptyStateActions>10<Button>Create collection</Button>11<Buttonvariant="ghost">Learn more</Button>12</EmptyStateActions>13</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.
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.
