ComposedEmptyState is the empty state of a page region: EmptyState placed with an optional illustration, a primary action, a secondary action, and a size and tone the caller picks. The inputs, slots, and variants are declared in schema.ts.
What it does and does not do
It places. It fills the block axis of the region it sits in without a fixed height, centers EmptyState in it, and renders the two actions side by side. Give it a parent with a definite height (a flex parent, a panel body, the page body); in an auto-height parent it takes the height of its content.
It does not decide why the region is empty. The caller passes the copy, the glyph, and the tone. It does not fetch data and has no loading or error logic. A caught render error stays with ErrorBoundary; ComposedEmptyStateTone.Error is only the visual for a failure the caller reports.
It is not EmptyText. EmptyText is the muted line inside a field or cell. EmptyState remains the component; this block is the placement.
Size
Size
Use
Padding
Copy column
Inline
A row, a card body, a menu
none
no cap; takes only the height it needs
Panel
A panel or section body
--space-24 block, --space-16 inline
--dialog-width-sm
Page (default)
The body of a page
--space-48 block, --space-24 inline
--dialog-width-md
Panel and Page fill the region (min-block-size: 100%) and center their content on both axes. The block sets no height of its own.
Tone
The tone is the caller's classification of why the region is empty. It sets one thing: whether the block is a live region.
Tone
Use
Live region by default
NoResults
A search or filter matched nothing
yes (role="status")
NoData (default)
Nothing has been created or received yet
no
Error
The data could not be shown
no
Permission
The person may not see the data
no
Pass announce to override the default in either direction. The block never sets role="alert".
The block imports no glyph, so it picks no icon for a tone. Pass the icon the tone calls for (the stories use search, inbox, alert, and lock) and an illustration when the region has room for one.
Media
icon is a glyph in EmptyState's neutral icon well. Decorative.
illustration is an Icon or an Image above the icon well. The block hides it from assistive technology, so the title and description must carry the meaning. Size the Icon yourself.
Actions
primaryAction recovers the region ("Clear filters") or creates the first record ("Create queue"). Normally one Button.
secondaryAction is a lesser path, such as documentation or configuration. A Button or a Link. It renders after the primary action and wraps below it when the column is narrow.
Controls render at their default size (Large). Use one primary action at most, and put it first.
Styles
Load @prepared911/ui/styles.css once at the document root.