;
};
Empty states appear when a section, page, or workflow has nothing to show yet. A good empty state explains the situation, reduces uncertainty, and helps people recover by pointing them toward the next meaningful action.
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
Use an icon when a compact, symbolic visual is enough to communicate the empty state quickly and keep the message lightweight.
Use an illustration when a more expressive or context-rich visual helps people understand the situation and feel guided toward the next step.
## Anatomy
An empty state is intentionally simple, but it can combine several layers of guidance depending on how much orientation or recovery support people need.
| 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.
Use an icon for simpler product moments and a richer illustration only when it adds meaningful context to the empty state.
Pair the message with one clear next action when people need help creating, finding, or restoring content.
Explain what is missing or unavailable before telling people what they can do next.
Use a short description when the title alone is not enough to reduce uncertainty or guide the next action.
Use `small`, `medium`, or `large` based on the available space and the prominence the empty moment needs.
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.
Title
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Title
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqEmptyState } from "@beeq/react";
Title
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqEmptyState } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqEmptyState],
template: `
Title
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Title
```
Keep the title direct and outcome-oriented. State what is missing, not just that the page is empty.
## Options
### With body
Use body content when the empty state needs a short explanation or a little more guidance about what happens next.
:host {
gap: var(--bq-spacing-xxl4) !important;
}
Title
Description
Title
Description
Link
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Title
Description
Title
Description
Link
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqEmptyState } from "@beeq/react";
Title
Description
Title
Description
Link
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqEmptyState } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqEmptyState],
template: `
Title
Description
Title
Description
Link
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Title
Description
Title
Description
Link
```
### 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.
:host {
gap: var(--bq-spacing-xxl4) !important;
}
Title
Description
Link
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Title
Description
Link
```
Do not overload an empty state with many equal-priority actions. If people need several next steps, pick the primary recovery path and move secondary options elsewhere.
### 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
Do
Combine a clear title with a short description when people need extra context. A title alone is often not enough to guide recovery.
Don't
Do not leave people with a vague message that explains nothing beyond the fact that the page is empty.
Do
Use one clear primary [Button](/components/button) or link to show the most useful next step.
Don't
Do not add too many competing calls to action. Too many choices weaken the guidance the empty state is supposed to provide.
Do
Use a representative icon or illustration and place the empty state where it is easy to notice, usually centered within the available space.
Don't
Do not use decorative art that suggests the wrong situation or distracts from the actual message.
Do
Match the empty state size to the available layout so the message feels intentional instead of oversized or easy to miss.
Don't
Do 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 empty `alt` value.
* **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.
Learn more about [styling with shadow parts](/guides/styles#component-shadow-dom-parts) and [CSS custom properties](/guides/styles#global-css-custom-properties).
## Resources
Explore Empty State examples and sizes in Storybook
View the component source on GitHub
Empty states appear when a section, page, or workflow has nothing to show yet. A good empty state explains the situation, reduces uncertainty, and helps people recover by pointing them toward the next meaningful action.
An empty state is intentionally simple, but it can combine several layers of guidance depending on how much orientation or recovery support people need.
| 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.