Empty state
What a container shows when it has nothing to list; a glyph, a heading in the bright text colour, one sentence in the muted colour and an optional secondary action.
stable · light DOM · 4.0.0. Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.
Live variants
with-action
No components match
Three filters are active; none of the 67 components passes all of them.
<j3w1-empty-state id="example-empty-state-with-action"><div class="empty-state">
<span class="empty-state-glyph" aria-hidden="true">∅</span>
<h3 class="empty-state-heading">No components match</h3>
<p class="empty-state-text">Three filters are active; none of the 67 components passes all of them.</p>
<button class="empty-state-action" type="button">Clear filters</button>
</div></j3w1-empty-state>without-action
No notifications
New ones appear here and in the corner of the screen.
<j3w1-empty-state id="example-empty-state-without-action"><div class="empty-state">
<span class="empty-state-glyph" aria-hidden="true">·</span>
<h3 class="empty-state-heading">No notifications</h3>
<p class="empty-state-text">New ones appear here and in the corner of the screen.</p>
</div></j3w1-empty-state>Install and register
Use the exact version. If npm publication is pending, install the release tarball from the installation guide.
npm install --save-exact @j3w1/ui@4.0.0import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/empty-state.css';
import '@j3w1/ui/register/empty-state';Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.
Copy the complete implementation
npx --package=@j3w1/ui@4.0.0 j3w1-ui copy empty-state --out ./vendor/j3w1/empty-stateThe CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.
Public API
attributes
| Name | Type / signature | Meaning |
|---|---|---|
disabled | CustomEvent | Disable the native controls owned by this instance. |
loading | CustomEvent | Mark the primary control busy and prevent duplicate activation. |
properties
| Name | Type / signature | Meaning |
|---|---|---|
disabled | boolean | Delegates disabled state to native children. |
name | string | Native control name; application form keys remain explicit. |
methods
| Name | Type / signature | Meaning |
|---|---|---|
refresh | (): void | Reconnect behavior after replacing native child structure. |
focus | (options?: FocusOptions): void | Focus the first usable native control. |
dismiss | (id?: string): void | Dismiss a message; focused actions move to the next available control. |
events
| Name | Type / signature | Meaning |
|---|---|---|
j3w1-dismiss | CustomEvent | Cancelable message dismissal. |
j3w1-retry | CustomEvent | Request recovery; the host owns the result. |
j3w1-action | CustomEvent | An explicit message action. |
Dependencies and verification
Registered components: none. Style dependencies: none.
Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.
Full implementation manifest, API and token dependency closure
Canonical specification
Empty state empty-state
What a container shows when it has nothing to list; a glyph, a heading in the bright text colour, one sentence in the muted colour and an optional secondary action.
Report an issue with this component
Tokens
Focus a role to inspect its values; follow its link for persistent usage and source details.
| Part | Role | Value | Use |
|---|---|---|---|
root.bg | color.surface.defaultapproveduse | #0d0707 | D-041 surface.default: color.primitive.modern.panel. |
root.border | color.border.dividerapproveduse | #482b2b | D-041 border.divider: color.primitive.modern.divider. |
glyph.text | color.icon.decorativeapproveduse | #986f72 | D-041 icon.decorative: color.primitive.modern.control. |
heading.text | color.text.brightapproveduse | #ffa2a7 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
text.text | color.text.mutedapproveduse | #d4868b | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
action.text | color.action.secondary.textapproveduse | #ffa2a7 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
action.border | color.action.secondary.borderapproveduse | #986f72 | D-041 action.secondary.border: color.primitive.modern.control. |
action.bg-hover | color.action.secondary.hover-bgobserveduse | #630f0d | Secondary button hover. |
action.ring | color.interaction.focus.ringobserveduse | #e53935 | 1px dashed focus ring on controls and rows. |
State matrix
Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).
| State | With action | Without action |
|---|---|---|
default | No components matchThree filters are active; none of the 67 components passes all of them. | No notificationsNew ones appear here and in the corner of the screen. |
Purpose
Replaces a blank pane, an empty table body or a filtered-out list: it says what is empty and offers the one action that changes it, when there is one. A failure is the error state; a wait is the loading indicator.
Anatomy
Parts as listed in the anatomy.
States
| State | Visual | Non-colour channel |
|---|---|---|
| default | glyph, heading and sentence centred; the action, when present, below them | the worded heading; the action is a real button |
No states of its own; the action takes the secondary button’s hover and ring.
Keyboard
As in the key table. When a filter empties a list that had focus inside it, focus moves to the region’s heading, not into the empty state, so the person hears where they are.
Accessibility
The heading is a real heading at the region’s level, so the empty state appears in the outline; the sentence follows it in reading order. When content becomes empty after an action (filter, delete), a polite live region announces the heading text. The action is never the only route: filters can also be cleared where they were set. Text meets 4.5:1; the action border 3:1.
Portability
A toolkit with only a placeholder string adds the action as a separate button below the view.
Non-examples
An illustration or mascot. A primary (filled) call to action. A blank pane. A greyed-out table header with no message. Only “No data”. A heading in the accent red. An empty state shown while loading. Centred text in a rounded, shadowed card.
Contrast report
6 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.
| Pair | State | Kind | Foreground | Background | Ratio | Min | Result |
|---|---|---|---|---|---|---|---|
| empty-state default text | default | text | color.text.muted #d4868b | color.surface.default #0d0707 | 7.22 | 4.5 | pass |
| heading on the panel surface | — | text | color.text.bright #ffa2a7 | color.surface.default #0d0707 | 10.45 | 4.5 | pass |
| action text on the panel surface | — | text | color.action.secondary.text #ffa2a7 | color.surface.default #0d0707 | 10.45 | 4.5 | pass |
| action boundary on the panel surface | — | ui | color.action.secondary.border #986f72 | color.surface.default #0d0707 | 4.62 | 3 | pass |
| glyph (decorative) | — | ui | color.icon.decorative #986f72 | color.surface.default #0d0707 | 4.62 | 1 | pass |
| container edge (decorative) | — | ui | color.border.divider #482b2b | color.surface.canvas #000000 | 1.66 | 1 | pass |
Keys
| Key | Action |
|---|---|
| Tab | Reaches the action when present; the block itself is never focusable. |
| Enter / Space | Activates the action. |
For agents
Component JSON ·Implementation brief ·Build a task kit ·
Related: error-state loading-indicator list table data-table button
Stress fixtures: FX-LONG FX-320 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-STATE-MATRIX