Empty State
When to use it
Section titled “When to use it”From the Lumo.Web.Component.V1.0.Complete library — theUse an empty state when a list, card or page has nothing to show — no results, nothing created yet, a failed load, or no permission.
empty-state description, read 2026-10-19.Where it goes
Section titled “Where it goes”- in the empty region of a list, card or page
When not to use it
Section titled “When not to use it”- Don’t leave the user without a next step; always give the action.
- No alternative named. The source states the prohibition without saying what to reach for instead.
What each variant is for
Section titled “What each variant is for”| Property | Value | What it is for |
|---|---|---|
size |
sm |
not stated in the source |
size |
md |
not stated in the source |
Accessibility
Section titled “Accessibility”- the title is a <p> by default and titleAs promotes it to a real heading, so a page-level empty state can take its place in the outline
src/components/emptyState/emptyState.jsx:44 - the medallion icon is decoration
src/components/emptyState/emptyStateIcon.jsx:22
Composition
Section titled “Composition”Nothing in the stories shows this component composed with another.
What this version promises
Section titled “What this version promises”See Versioning. At 0.1.0 the public surface is the named exports of src/index.ts; this component is one of them.
This component’s release verdict is Cleared and its Development status reads Released. A Cleared verdict is a recommendation with reasons, recorded in its release review — a human decides whether a release happens, and no agent approves its own work.
Every story that is not a variant-matrix row, embedded live from the deployed Storybook in both themes. The matrix itself is on the Design tab.
Playground
Section titled “Playground”↳Icon slot
Section titled “↳Icon slot”↳Action slot (composes Button)
Section titled “↳Action slot (composes Button)”In context (inside Card)
Section titled “In context (inside Card)”Import
Section titled “Import”import { EmptyState } from '@ds-house/lumo-design-system';| Prop | Type | Default | Notes |
|---|---|---|---|
size |
`‘sm’ | ‘md’` | 'sm' |
title |
string |
'No use cases match these filters' |
Figma Title. The headline. Always shown — the node has no boolean for it. |
description |
boolean |
true |
Figma Description (the boolean property). Shows the supporting line. |
descriptionText |
string |
'Try removing a filter, or ask our team to research a custom use case.' |
Figma Description (the text property). Renamed because the set spells two different properties Description; see docs/naming-conflicts.md. |
action |
boolean |
true |
Figma Action. Reveals the ↳Action slot. |
children |
React.ReactNode |
null |
The ↳Action slot. Put a Button here — the component description says to always give the user a next step. Named children per the Card precedent in docs/naming-conflicts.md, because action is taken by the boolean above. |
icon |
React.ReactNode |
null |
The ↳Icon slot. Swaps what sits inside the medallion. Defaults to the node’s own Icon/check instance (94:10 / 94:18). |
iconName |
string |
'check' |
Material Symbols glyph for the default icon, when icon is not supplied. |
titleAs |
`‘p’ | ‘h1’ | ‘h2’ |
className |
string |
'' |
Union types
Section titled “Union types”size:'sm'|'md'titleAs:'p'|'h1'|'h2'|'h3'|'h4'|'h5'|'h6'
Tokens it needs
Section titled “Tokens it needs”| Token | Light | Dark |
|---|---|---|
--body-body2 |
not in the build | — |
--body-body3 |
not in the build | — |
--body-body6-intense |
not in the build | — |
--border-radius-full |
not in the build | — |
--color-bg-brand-subtle |
not in the build | — |
--color-icon-brand |
not in the build | — |
--color-text-bold |
not in the build | — |
--color-text-secondary |
not in the build | — |
--heading-h4 |
not in the build | — |
--size-56 |
not in the build | — |
--size-72 |
not in the build | — |
--size-icon-md |
not in the build | — |
--spacing-gap-horizontal-sm |
not in the build | — |
--spacing-gap-md |
not in the build | — |
--typography-fontweight-regular |
not in the build | — |
A dash under Dark means the token does not change between themes.
Storybook’s own props table
Section titled “Storybook’s own props table”The Figma node
Section titled “The Figma node”The variant matrix
Section titled “The variant matrix”Each row as the set draws it, in both themes.
Size = sm (94:7)
Section titled “Size = sm (94:7)”Size = md (94:15)
Section titled “Size = md (94:15)”Description = false
Section titled “Description = false”Action = false
Section titled “Action = false”Description = false, Action = false
Section titled “Description = false, Action = false”Matrix
Section titled “Matrix”What Figma never bound, and the gaps recorded against it
Section titled “What Figma never bound, and the gaps recorded against it”The build report docs/emptyState.md records no “Design gaps” section.
Where Figma and this repo disagree across the system, see the disagreements record.
Every commit touching this component and its subcomponents — a change to a subcomponent changes the component, and a log that reads only the parent file misses it.
| Commit | Date | Shipped in | Subject |
|---|---|---|---|
2b94809 |
2026-10-19 | unknown | Write the ten component intent files |
c8bc699 |
2026-10-18 | unknown | Add the test suite, and retire the deliberate stop |
9525e0f |
2026-10-17 | unknown | Make the repo a publishable npm package |
50cd21b |
2026-10-12 | unknown | Build Empty State from Figma 94:1862 — two sizes, six gaps reported |
7ccfbbb53757.