EmptyState

Placeholder block for empty lists, zero search results, and first-run screens.

Status: stable. Group: display. Markdown version: /design-system/components/empty-state.md

When to use

EmptyState fills the space where content should be with an explanation and a way forward: a decorative icon, a real heading, up to two sentences of description, and an action slot for Buttons. Use sm inside panels and cards, md in content areas, lg on full pages. For failures use AlertBanner; EmptyState is for legitimate absence.

When not to use

Do not use EmptyState for errors or loading; AlertBanner owns failures and Skeleton owns loading.

Look-alikes

AlertBanner: Do not use EmptyState for errors or loading; AlertBanner owns failures and Skeleton owns loading.
Center: Use it for single focal content: Spinner, EmptyState, a logo lockup.
Skeleton: Do not use EmptyState for errors or loading; AlertBanner owns failures and Skeleton owns loading.

Props

EmptyState props
Prop	Type	Default	Description	Required
`icon`	`string`	none	Phosphor icon name rendered decoratively above the title.	No
`title`	`string`	none	Short headline stating what is empty.	Yes
`description`	`string`	none	One or two sentences explaining why, or what to do next.	No
`headingLevel`	`"h2" \| "h3" \| "h4"`	`h2`	Heading tag for the title. Defaults to `h2`; set it to fit the page outline.	No
`size`	`"sm" \| "md" \| "lg"`	`md`	Size token. Defaults to `md`.	No
`children`	`React.ReactNode`	none	Action slot; typically one primary Button, optionally a secondary.	No

Variants

Available sizes: sm, md, lg (default md).
Allowed headingLevel values: h2, h3, h4 (default h2).

Invalid combinations

The contract records no invalid combinations.

Keyboard

EmptyState keyboard behaviour
Key	Behaviour
Tab	Reaches actions in the slot.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

EmptyState rules
Level	Rule	How it is checked
MUST	ARIA: Title is a real heading; headingLevel must fit the page outline.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Icon is decorative (aria-hidden)	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	Required stories produce no axe violations at the configured severity.	Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8.
MUST	The accessibility tree (role, name, state) matches the committed snapshot for every required story.	Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2.
MUST	The component remains legible and operable under a real browser forced-colors: active pass.	Automated by `npm run test:stories:hc`.
MUST	Every documented keyboard interaction works as specified.	Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2.
MUST	A human completed an end-to-end accessibility review of this component.	Manual review, last on 2026-11-04.
SHOULD	Name what is empty in the title ("No projects yet"), not a generic "Nothing here".	Not stated in the contract.
SHOULD	Give a way forward: an action button, or a description telling the user what will populate this space.	Not stated in the contract.
SHOULD	Set headingLevel so the title fits the page outline (h3 inside a card that sits under an h2).	Not stated in the contract.
SHOULD	Keep zero-search-results copy actionable: suggest clearing filters or broadening the term.	Not stated in the contract.
SHOULD NOT	Do not stack more than two actions; one primary path plus one escape hatch.	Not stated in the contract.

Install and import

Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
Import: import { EmptyState } from "@digitaltableteur/react";
Entry point: @digitaltableteur/react/feedback exports it too.
Styles: import @digitaltableteur/react/style.css once at the app boundary.
Also available as the custom element <dt-empty-state>; see the custom elements manifest.