Empty state

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Usage

Explain why there's nothing to show and offer possible next steps. Distinguish first use, no search results, and insufficient permissions. When other content is present, show the state in the relevant region instead of replacing the whole screen.

Don't present an error as an empty success state. Use InlineMessage instead. Don't prompt people to create something they lack permission for. Don't make an action they can't perform the primary button. Offer permission guidance instead.

Size: SizeProvider size="small" resizes the whole composition, including portals. The default size is Default. Size guidance and comparisons

Anatomy

Root → optional decorative Icon + Title(h3) + Description + Actions

Keyboard and accessibility

It doesn't take focus or create a live region. Set Title.level to fit the surrounding heading hierarchy. Offer clearing a search, creating an item, and permission guidance as clearly named buttons or links.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

import { EmptyState, Button } from '@surflane/ui'

<EmptyState.Root>
  <EmptyState.Title>No matching environments</EmptyState.Title>
  <EmptyState.Description>
    Try another name or clear the filters.
  </EmptyState.Description>
  <EmptyState.Actions>
    <Button onClick={clearFilters}>Clear filters</Button>
  </EmptyState.Actions>
</EmptyState.Root>

Key API

The table lists the common wrapper's main props. See the package type declarations for the full types.

Related tokens