Empty state

Explains missing content and offers a relevant action.

When to use

Use an empty state when a region has no content, no matching results or no entries yet. Explain the reason and offer a useful next action. Use an Alert when the absence results from an error that needs attention.

Default

Use .empty-state when content is absent. Choose a contextual heading. It is not a live region; announce dynamic outcomes separately when needed.

No matching records

Try another search term or clear the active filters.

Clear filters
HTML
<section
	class="empty-state"
	aria-labelledby="empty-search-title"
	aria-describedby="empty-search-description">
	<span class="empty-state-icon" aria-hidden="true">
		<!-- Decorative search icon -->
	</span>
	<h3 class="empty-state-title" id="empty-search-title">No matching records</h3>
	<p class="empty-state-description" id="empty-search-description">
		Try another search term or clear the active filters.
	</p>
	<div class="empty-state-actions">
		<a class="btn btn-solid btn-primary" href="/records">Clear filters</a>
		<button class="btn btn-outline btn-secondary" type="button">Save search</button>
	</div>
</section>

Compact

Use .empty-state-compact in small regions.

No saved views

Save a filter combination to return to it later.

HTML
<section class="empty-state empty-state-compact" aria-labelledby="empty-views-title">
	<h3 class="empty-state-title" id="empty-views-title">No saved views</h3>
	<p class="empty-state-description">Save a filter combination to return to it later.</p>
	<div class="empty-state-actions">
		<button class="btn btn-solid btn-primary btn-sm" type="button">Create view</button>
	</div>
</section>

Accessibility and behavior

  • Connect the region to its heading and description. Keep illustrations decorative when the message already conveys their meaning.
  • Provide a direct recovery action, such as clearing filters or adding the first entry. Use links for navigation and buttons for changes.
  • The component is not a live region. When it replaces results dynamically, announce a concise result summary separately if needed and preserve focus on a usable control.

CSS variables

Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.

TokenDefaultPurposeScope / state
--empty-state-max-width36remMaximum width..empty-state
--empty-state-min-height0Minimum height..empty-state
--empty-state-padding-yvar(--spacer-5)Top and bottom padding..empty-state
--empty-state-padding-xvar(--spacer-3)Left and right padding..empty-state
--empty-state-gapvar(--spacer-3)Space between child elements..empty-state
--empty-state-icon-size3remWidth and height of the illustration or icon..empty-state
--empty-state-icon-colorvar(--text-muted)Illustration or icon color..empty-state
--empty-state-title-colorvar(--text-color)Title text color..empty-state
--empty-state-description-colorvar(--text-muted)Supporting text color..empty-state
--empty-state-actions-gapvar(--spacer-2)Space between actions..empty-state