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.
<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.
<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.
| Token | Default | Purpose | Scope / state |
|---|---|---|---|
--empty-state-max-width | 36rem | Maximum width. | .empty-state |
--empty-state-min-height | 0 | Minimum height. | .empty-state |
--empty-state-padding-y | var(--spacer-5) | Top and bottom padding. | .empty-state |
--empty-state-padding-x | var(--spacer-3) | Left and right padding. | .empty-state |
--empty-state-gap | var(--spacer-3) | Space between child elements. | .empty-state |
--empty-state-icon-size | 3rem | Width and height of the illustration or icon. | .empty-state |
--empty-state-icon-color | var(--text-muted) | Illustration or icon color. | .empty-state |
--empty-state-title-color | var(--text-color) | Title text color. | .empty-state |
--empty-state-description-color | var(--text-muted) | Supporting text color. | .empty-state |
--empty-state-actions-gap | var(--spacer-2) | Space between actions. | .empty-state |