HyEmptyState

Usage examples on this page are written for Lit / plain HTML (<hy-empty-state>). The same component ships as HyEmptyState in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A placeholder for "no data / no results / error / loading" regions.

Collapses the hand-rolled empty + load-state markup duplicated across an app (icon/illustration + heading + body + actions) into one element. A state axis (empty | loading | error) absorbs the {loading}…{error}…{empty} triplet with a built-in spinner and retry button; a variant axis presets the icon + copy per scenario.

Key Features:

• Scenario presets (no-data, no-results, error, not-found, success, offline)
• Async-state mode (loading → built-in spinner; error → retry button firing retry)
• Search-aware no-results via the query prop
• Compact (inline) vs medium (full-region) sizes
• Dark-mode raster media swap (light-src / dark-src + theme, mirroring hy-logo)
• Slots for media / title / description / actions / footer

Accessibility Highlights:

• role="status" (implicit aria-live="polite") so a list becoming empty after filtering is announced to screen readers
• High contrast + forced-colors support

Examples

No-data with an action

<hy-empty-state variant="no-data" heading="No design systems yet">
  Create your first design system to get started.
  <hy-button slot="actions" variant="brand">New design system</hy-button>
</hy-empty-state>

Search-aware no-results

<hy-empty-state variant="no-results" query="brutalist"></hy-empty-state>

The async triplet, one element

<hy-empty-state state="loading"></hy-empty-state>
<hy-empty-state state="error"></hy-empty-state>
<hy-empty-state state="empty" variant="no-data"></hy-empty-state>

API

Properties

Property	Attribute	Type	Default	Description
variant	variant	'no-data' | 'no-results' | 'error' | 'not-found' | 'success' | 'offline'	'no-data'	Scenario preset determining the default icon and copy.
state	state	'empty' | 'loading' | 'error'	'empty'	Async-state mode. loading shows a spinner; error shows the error layout with a retry button.
size	size	'compact' | 'medium'	'medium'	Size / density. compact for inline placements (empty rows, side panels); medium for centered full-region placements.
heading	heading	string | undefined	—	Heading text. The title slot wins if both are provided.
description	description	string | undefined	—	Description text. The default slot wins if both are provided.
query	query	string | undefined	—	Search query. For variant="no-results", drives the default No results for "…" heading.
lightSrc	light-src	string	''	Raster media source for light theme.
darkSrc	dark-src	string	''	Raster media source for dark theme.
theme	theme	'light' | 'dark'	'light'	Which media source to show.
label	label	string | undefined	—	Accessible label for the region (applied as aria-label).

Events

Event	Detail	Description
retry	—	Fired when the built-in retry button (shown in state="error") is clicked. Detail: {}

Slots

Slot	Description
media	The visual — icon, illustration, or animation. Defaults to a variant icon.
default	The description body (richer than the description prop).
title	Heading override.
actions	Primary + secondary action buttons.
footer	Help link / "learn more".

CSS Parts

Part	Description
base	The empty-state region wrapper.
media	The media (icon/illustration) container.
title	The heading element.
description	The description element.
actions	The actions slot container.
footer	The footer slot container.

CSS Custom Properties

Property	Description
--hy-empty-state-padding	Padding around the region.
--hy-empty-state-gap	Gap between media / title / description / actions.
--hy-empty-state-foreground-title	Heading color.
--hy-empty-state-foreground-description	Description / footer color.
--hy-empty-state-foreground-media	Default media icon color.