Prepared Docs

EmptyState from @prepared911/ui-core composes an icon, heading, description, and optional actions. The component renders readable copy and delegates interactive behavior to its actions; your job is to name the region, prioritize actions correctly, and let the live region announce the state when it appears asynchronously.

What the component handles

Semantic heading. title renders as a heading at an appropriate level.
Readable copy. description renders as body text.
Action slots. primaryAction and secondaryAction render in a predictable order and keep focus flow linear.
Decorative icon. icon is rendered aria-hidden by default.

What you must provide

A named region. Wrap the empty state in a landmark (<section aria-labelledby="..."> or role="status" when it appears asynchronously after a filter change) so assistive tech can route to it.
Action priority. Exactly one primary action (or none); put the most likely next step first. Don't stack two primary buttons.
Announcements for filtered empties. When filters or search return no results, wrap the empty state in role="status" with aria-live="polite" so the rotor announces the result without stealing focus.

Keyboard behavior

Actions inherit Button keyboard behavior (see Button accessibility).
The empty state itself is not focusable unless it's an asynchronous result—do not add tabIndex to the region.

Semantics and roles

Section landmark with a heading that names the region.
role="status" when the empty state results from an async filter or search change.
Icon is decorative (aria-hidden="true") with meaning conveyed by the heading and description.

Reduced motion

Skip entrance animations on prefers-reduced-motion: reduce; a static appearance is sufficient to communicate the new state.

Known caveats

Blank-slate vs error. Use EmptyState for zero-data and filtered states. For failures ("couldn't load incidents"), use an error state with a retry action and a different tone—don't reuse EmptyState copy.
Action without context. A bare "Add item" with no explanation wastes the moment. Use the description to explain what the user can do here and why it matters.

Empty State / API and Development

File Upload / Usage

What the component handles

What you must provide

What the component handles

Semantic heading. title renders as a heading at an appropriate level.
Readable copy. description renders as body text.
Action slots. primaryAction and secondaryAction render in a predictable order and keep focus flow linear.
Decorative icon. icon is rendered aria-hidden by default.

What you must provide

A named region. Wrap the empty state in a landmark (<section aria-labelledby="..."> or role="status" when it appears asynchronously after a filter change) so assistive tech can route to it.
Action priority. Exactly one primary action (or none); put the most likely next step first. Don't stack two primary buttons.
Announcements for filtered empties. When filters or search return no results, wrap the empty state in role="status" with aria-live="polite" so the rotor announces the result without stealing focus.

Keyboard behavior

Actions inherit Button keyboard behavior (see Button accessibility).
The empty state itself is not focusable unless it's an asynchronous result—do not add tabIndex to the region.

Semantics and roles

Section landmark with a heading that names the region.
role="status" when the empty state results from an async filter or search change.
Icon is decorative (aria-hidden="true") with meaning conveyed by the heading and description.

Reduced motion

Skip entrance animations on prefers-reduced-motion: reduce; a static appearance is sufficient to communicate the new state.

Known caveats

Blank-slate vs error. Use EmptyState for zero-data and filtered states. For failures ("couldn't load incidents"), use an error state with a retry action and a different tone—don't reuse EmptyState copy.
Action without context. A bare "Add item" with no explanation wastes the moment. Use the description to explain what the user can do here and why it matters.