EmptyState

Absence with a next step.

<sui-empty-state>FeedbackStable

About

Absence or outcome surface for a list with nothing in it, a search with no matches, a period that closed cleanly or an import that failed. Say what is missing and offer the next action in the actions slot; never apologize. Four variants share one anatomy, so a screen keeps its shape between empty and done.

Usage

<sui-empty-state heading="No open bills." description="Enter a bill to get started."> <sui-button slot="actions" variant="accent" label="Enter bill"></sui-button> </sui-empty-state> <script type="module"> import { defineCustomElements } from "@shineui/core/loader"; import "@shineui/core/shineui.css"; defineCustomElements(); </script>

import { SuiEmptyState } from "@shineui/react"; import "@shineui/core/shineui.css"; export function Example() { return ( <SuiEmptyState heading="No open bills." description="Enter a bill to get started."> <sui-button slot="actions" variant="accent" label="Enter bill"></sui-button> </SuiEmptyState> ); }

import { Component } from "@angular/core"; import { SuiEmptyState } from "@shineui/angular"; @Component({ standalone: true, imports: [SuiEmptyState], template: `<sui-empty-state heading="No open bills." description="Enter a bill to get started."><sui-button slot="actions" variant="accent" label="Enter bill"></sui-button></sui-empty-state>`, }) export class Example { }

Basic

Say what is missing and offer the next action; never apologize. The icon is aria-hidden, so the heading and body are the whole accessible content, and nothing here manages focus: when the action replaces this surface, the host page decides where focus lands. heading-level moves the h2 to h3 or h4.

<sui-empty-state heading="No open bills." description="Enter a bill to get started."> <sui-button slot="actions" variant="accent" label="Enter bill"></sui-button> </sui-empty-state>

Variants

empty, success, error and not-found share one anatomy, so a screen does not switch shapes between empty and done. success is navy, never green, and only error carries role="alert", so only a failed operation interrupts a screen reader; do not reach for error on a merely empty list.

Rich body and actions

Put markup in the default slot when the body needs more than a sentence; a filled slot replaces description rather than stacking under it. The actions slot takes a row of buttons, one accent button at most.

No results for riverbend in July. Try a wider date range.

<sui-empty-state variant="not-found" heading="No matches." description="Ignored while the slot is filled."> No results for <b>riverbend</b> in July. Try a wider date range. <sui-button slot="actions" variant="accent" label="Clear filters"></sui-button> <sui-button slot="actions" variant="ghost" label="Search all years"></sui-button> </sui-empty-state>

Compact and bare

compact tightens the padding and the icon well for a table body or a narrow column. bare drops the card frame, for a surface that already has one.

API

`<sui-empty-state>`

Properties

Property	Attribute	Type	Default	Description
`bare`	`bare`	`boolean`	`false`	Drops the card frame (transparent, no border).
`compact`	`compact`	`boolean`	`false`	Tighter padding, 40px icon well, 13.5px heading.
`description`	`description`	`string`string \| undefined		Supporting line, max 360px wide. Ignored when the default slot is filled.
`heading`	`heading`	`string`	`''`	Headline. Named `heading` because `title` is the native tooltip attribute.
`headingLevel`	`heading-level`	`2 \| 3 \| 4`	`2`	Heading level of the title element, 2 to 4. The size does not change with it.
`icon`	`icon`	`string`string \| undefined		Font Awesome class overriding the variant icon.
`variant`	`variant`	`"empty" \| "error" \| "not-found" \| "success"`	`'empty'`	Outcome flavour: `empty`, `success` (the brand, never a green), `error` (the deep accent) or `not-found`. Sets the icon well colors and the default icon. Only `error` renders `role="alert"`, so only a failed operation interrupts a screen reader; do not use it for a merely empty list. The icon is `aria-hidden`, so the heading and body are the whole accessible content.

Slots

Slot	Description
`(default)`	Body content with markup, for example "No results for riverbend" with a clear-filters link. It shares the body position with `description`, so it replaces it rather than stacking.
`actions`	Buttons rendered in a row under the description (one accent button at most). Nothing here manages focus: when an action replaces this surface, the host page decides where focus lands.

Theming

Every design token this element can render with, read from its own stylesheets and the ones it imports. Set a token on :root or on any ancestor and every use below follows it. The values shown are the ones in the theme you are viewing. The list is read per stylesheet, so an element that imports a shared drawing module lists that module's tokens too, whether or not it paints with all of them.