Components / Feedback and display

EmptyState

What to show where content will be: no items yet, no search results, nothing selected. It says what is missing and offers the next step.

Source Edit this page

Heading and next step

When to use

A list or area with nothing in it yet, with a way to add the first item.
No results for a search or filter, with a way to widen it.

Use something else when:

something went wrong: a Notice
content is still loading: a loading indicator such as LoadingDots

Usage

tsx

import { Button, EmptyState } from "@arshad-shah/cynosure";
import { search } from "@arshad-shah/cynosure/icons";

<EmptyState
  icon={search}
  title="No matches"
  description="Try fewer words or clear the filters."
  headingLevel={2}
  actions={<Button onClick={clearFilters}>Clear filters</Button>}
/>

Pick headingLevel so the title fits the page outline: one level below the heading of the area it fills.

No results

Narrow panels

With size="sm" it uses less space. Long titles wrap and the actions stack, so it fits extension popups.

Wraps in anarrow panel

Props

Every prop of EmptyState
Prop	What it does	Type
`title`Required	The heading: what is empty or missing.	`ReactNode`
`icon`	A Facet icon shown above the title (decorative).	`IconData`
`description`	A sentence under the title.	`ReactNode`
`actions`	Buttons for the next step ("Create a project", "Clear filters").	`ReactNode`
`headingLevel`	Heading level of the title, to fit the page outline (default 3). 1 when the empty state is the page itself (a not-found page): the look stays the same.	`2 \| 3 \| 4 \| 5 \| 6 \| 1`
`size`	`sm` for panels and popups, `md` for page areas.	`"sm" \| "md"`
`className`	Added to the root element, for layout.	`string`
`style`	Layout only. Restyle through --cy-empty-state-* tokens.	`CSSProperties`

Generated from the type definitions in @arshad-shah/cynosure 0.5.0.

Behaviour and accessibility

Heading: the title is a real h2 to h6, so it shows up in the page outline and heading navigation.
Icon: decorative (aria-hidden).
Contrast: title and description are at least 4.5:1 on the page background in light and dark modes.
It has no interaction of its own; the actions are ordinary Buttons.

Theming

Tokens: --cy-empty-state-gap, --cy-empty-state-padding and --cy-empty-state-max-width (line length of the text).

createTheme({ components: { emptyState: { maxWidth: "48ch" } } });

Notice · Button

These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.

When to useLink to "When to use"

UsageLink to "Usage"

Narrow panelsLink to "Narrow panels"

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

ThemingLink to "Theming"