Use empty states when the absence of content is meaningful and persistent enough to deserve guidance. If content is only loading or momentarily unavailable, use a loading or error pattern instead.
When to use
Use empty states when
- A page or section has no data yet and people need orientation
- A first-time experience needs guidance before content exists
- The interface should explain what is missing and what action can create content
Do not use empty states when
- Content is still loading and a spinner or skeleton is more accurate
- The issue is a temporary system problem that should be communicated as an error state
- The page already contains enough surrounding guidance to explain what is happening
Patterns
Anatomy
| Part | Element | Description |
|---|---|---|
| 1 | Illustration or icon | A default icon or custom thumbnail slot that visually communicates the empty state |
| 2 | Title | The primary statement that explains what is missing or unavailable |
| 3 | Description | Optional supporting text placed in the body slot to add context or reassurance |
| 4 | Link | Optional inline guidance inside the body content that points to help, learning, or an alternate path |
| 5 | CTA buttons | Optional primary and secondary actions placed in the footer slot |
Design guidelines
Use empty states to orient people quickly, explain why nothing is shown, and make the next step obvious.Start with the reason
Explain what is missing or unavailable before telling people what they can do next.
Add only necessary detail
Use a short description when the title alone is not enough to reduce uncertainty or guide the next action.
Center the empty state within the available area when it represents the main content of the page or section, so the message is easy to notice without competing with unrelated UI.
Usage
Default
Use the default variant when you want the cleanest possible presentation and the title already communicates enough context.Options
With body
Use body content when the empty state needs a short explanation or a little more guidance about what happens next.With call to action
Use the footer when the empty state should help people recover immediately. Prefer one primary action. Add a secondary action only when it offers a clearly different path.Sizes
Choose size based on the available space and the prominence of the moment.medium is the default and works for most dashboard or section-level empty states.
| Size | When to use |
|---|---|
| Small | Dense layouts, side panels, compact cards, or mobile contexts where space is limited |
| Medium | Most standard application pages and sections |
| Large | Full-page empty states or moments where the message should feel more prominent |
Best practices
DoCombine a clear title with a short description when people need extra context. A title alone is often not enough to guide recovery.
Don’tDo not leave people with a vague message that explains nothing beyond the fact that the page is empty.
DoUse one clear primary Button or link to show the most useful next step.
Don’tDo not add too many competing calls to action. Too many choices weaken the guidance the empty state is supposed to provide.
DoUse a representative icon or illustration and place the empty state where it is easy to notice, usually centered within the available space.
Don’tDo not use decorative art that suggests the wrong situation or distracts from the actual message.
DoMatch the empty state size to the available layout so the message feels intentional instead of oversized or easy to miss.
Don’tDo not use a full-page large empty state inside a compact panel or card where it overwhelms the surrounding layout.
Accessibility
- Keep visuals decorative unless they carry meaning — if the thumbnail is only illustrative, hide it from assistive technology with
aria-hidden="true"or an emptyaltvalue. - Make the title and body self-sufficient — people should understand the state without needing to infer meaning from the artwork.
- Use semantic, keyboard-accessible actions — any recovery path in the footer should be a real button or link that can receive focus and has a clear label.
- Preserve reading order — title, description, and actions should follow a logical visual and DOM sequence.
- Do not rely on color or imagery alone — the message itself should explain what is happening and what can be done next.
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
size | size | The size of the empty state component | "large" | "medium" | "small" | "medium" |
Slots
| Slot | Description |
|---|---|
| (default) | The empty state title |
thumbnail | Replaces the default icon with custom visual content |
body | Supporting descriptive content displayed below the title |
footer | Actions displayed below the body |
Shadow parts
| Part | Description |
|---|---|
wrapper | The outer container inside the shadow DOM |
thumbnail | The container that wraps the icon or slotted thumbnail |
icon | The default bq-icon rendered when no thumbnail is provided |
title | The container that wraps the title content |
body | The container that wraps the body slot |
footer | The container that wraps the footer slot |
CSS custom properties
This component does not expose any CSS custom properties.Resources
Interactive playground
Explore Empty State examples and sizes in Storybook
Source code
View the component source on GitHub