> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK /dev/sdks/python/index.md; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; Aura UI /cdf/aura/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Empty state

> Empty states guide users when there is no content to display or when an error prevents data from loading. They serve to inform, assist, and encourage users toward the next steps.

<Badge color="blue">v1.0.0</Badge> | [View in Storybook](https://master--695bb4b1b8041ae09768950a.chromatic.com/?path=/docs/primitives-emptystate--docs)

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-emptystate--sizes" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-emptystate--sizes&viewMode=story&globals=theme:light" title="Empty state sizes story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

## When to use

* **First-time scenarios & user cleared:** use an Empty state where the user may not have data. An Empty state is a great way to explain what they can do to populate the screen and provide the call to action. If it's a user-cleared scenario, for example, they finished their to-dos or cleared an inbox, an Empty state might be positive and celebratory or encouraging of what to do next.
* **No results:** when a user searches for data, but the system cannot return any results, an Empty state is a great form of feedback to the user. Help them understand how best to modify their search.
* **Error management:** when something did not go as planned an Empty state can help guide the user back to the right path. Error messages paired with thoughtful guidance content can help the user resolve the error on their own or seek out the appropriate support channels. Error management might include permission issues, system issues or configuration required.

## When to use something else

Empty states are patterns with no established alternatives for their use cases. However, it's important to think critically about the Empty states and potential scenarios where restricting access may be a simpler approach. For example: if a user has access to many views within a page but all views are empty as a first-time user, it might be best to limit access to only the page where the first call to action is if such exists. Consider how seeing several empty state pages repeated could potentially frustrate a user. Alternatively, creating more custom content for each empty page could be more welcoming and helpful to the user.

## Dos and don'ts

* **Do** include a primary call to action Button to help guide the user to act fast. Use secondary buttons to provide a way back to a previous screen (if applicable) or to link to additional documentation.
* **Do** use illustrations that reflect the situation.
* **Do** use a default size for full pages or large containers. Use a compact size for small containers or Drawers and side panels.
* **Don't** use product-specific terms that the user may not yet understand or discuss content that is not relevant to that page.
* **Don't** adjust the styling or add alternative backgrounds to the container.
* **Don't** cover multiple call to actions in one Empty state. If there are multiple things a user can do, pick the most important and keep the focus on that action.

## Placement and alignment

Empty states always appear in the otherwise empty space, in the context of missing data. They can occur anywhere data is typically displayed, including but not limited to Tables, Cards, Menus, full pages and side panels. In general, content should be center-aligned, both horizontally and vertically, within their container.

## Behavior

* Occupies the primary content region until the user resolves the empty or error condition; primary CTA should map to the next constructive step.
* Illustrations and copy are static guidance, not a substitute for [Banner](/cdf/aura/primitives/banner) or [Alert](/cdf/aura/primitives/alert) for live system faults unless paired appropriately.
* Use partial data reloads: Trigger data fetching only for the specific component or section where the error or empty state occurred (e.g., refresh a side panel, not the entire app).
* Keep user input/preferences intact: Preserve things like selected filters, zoom levels, or scroll position when retrying.
* Visual feedback: Show a spinner or loading skeleton during retry. Disable retry button while request is in progress to avoid duplicate calls.

## Often used with

Primary (and optional secondary) [Button](/cdf/aura/primitives/button); illustration or icon slot; headings/copy—pair with [Search](/cdf/aura/primitives/search) or filters when "no results" depends on query.

## Accessibility

### Semantic hierarchy and context

* **Match surrounding heading levels:** Assign the empty state title the correct heading level (`<h2>`, `<h3>`) relative to its parent container rather than hardcoding arbitrary levels.
* **Maintain parent landmarks:** Render the empty state inside its parent region (for example within `<main>`, `<section>`, or a [Data grid](/cdf/aura/primitives/data-grid) container) so screen reader users retain section context when navigating by landmarks.

### Dynamic state changes and focus

* **Use live regions for filtered results:** If the empty state appears dynamically (for example a search query returns zero results), wrap the container or status text in an `aria-live="polite"` region or `role="status"` so the change is announced automatically.
* **Prevent focus loss on deletion:** If deleting the final item in a list triggers the empty state, manually shift keyboard focus to the empty state container (`tabIndex={-1}`) or its main call-to-action button to prevent focus from resetting to the top of `<body>`.

### Media and actionable elements

* **Hide decorative graphics:** Ensure decorative illustrations or SVGs carry `aria-hidden="true"` or `alt=""` so screen readers skip straight to the title and explanation.
* **Use explicit CTA labels:** Provide self-descriptive text for action buttons so they make sense when read out of context (for example "Clear active search filters" instead of "Reset", or "Create your first project" instead of "Add").

## Visual examples

The examples below are interactive and follow the doc site's theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

### Compact variant

Use the compact Empty state variant in small containers—such as a side panel, table cell, or drawer—where a full-page illustration would overwhelm the layout.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-emptystate--compact-variant" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-emptystate--compact-variant&viewMode=story&globals=theme:light" title="Empty state compact variant story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Full variant

Use the full Empty state variant on pages or large content areas when you have room for an illustration, heading, description, and a primary call to action.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-emptystate--full-variant" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-emptystate--full-variant&viewMode=story&globals=theme:light" title="Empty state full variant story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Full variant types

Choose among full Empty state types—such as first-time, no results, or error—to match the scenario and set the right tone for copy and illustration.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-emptystate--full-variant-types" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-emptystate--full-variant-types&viewMode=story&globals=theme:light" title="Empty state full variant types story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Full variant custom icon

Replace the default Empty state illustration with a custom icon when a product-specific metaphor fits better than the built-in artwork.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-emptystate--full-variant-custom-icon" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-emptystate--full-variant-custom-icon&viewMode=story&globals=theme:light" title="Empty state full variant custom icon story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### With action

Include a primary Button in the Empty state when users can resolve the empty condition directly—for example, Create item or Clear filters.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-emptystate--with-action" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-emptystate--with-action&viewMode=story&globals=theme:light" title="Empty state with action story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### No results

Use the no-results Empty state when a search or filter returns zero matches, and suggest how users can broaden or change their query.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-emptystate--no-results" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-emptystate--no-results&viewMode=story&globals=theme:light" title="Empty state no results story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### With custom message

Customize the Empty state message when the default copy does not fit—for example, permission errors, maintenance windows, or domain-specific guidance.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-emptystate--with-custom-message" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-emptystate--with-custom-message&viewMode=story&globals=theme:light" title="Empty state with custom message story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Title as

Set the Empty state title element—for example, `h2` instead of `h3`—to match the heading hierarchy of the surrounding page for correct document outline.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-emptystate--title-as" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-emptystate--title-as&viewMode=story&globals=theme:light" title="Empty state title as story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>