Skip to content
Cloaked Design SystemStatus

EmptyState

A calm full-region placeholder that centers a title, optional description, icon, and recovery action when an area has nothing to show.

Implementation preview
COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

8 stories
SELECTED EXAMPLE

Playground

Open controls
Playground selectedOpen canvas
Example sourcepackages/design-system/src/components/status/EmptyState/EmptyState.stories.tsxExport Playground

Implementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.

Stories + source JSON ↗

Local specification source status: preview. Implementation preview pending sign-off.

A calm full-region placeholder that centers a title, optional description, icon, and recovery action when an area has nothing to show.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off
Implementation API 1 entry point · source-derived preview

Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.

import { EmptyState } from '@cloakedinc/design-system';
EmptyStateEmptyStateProps

packages/design-system/src/components/status/EmptyState/EmptyState.tsx:35

PropTypePresenceNotes
titlestringRequiredHeadline naming what is missing. Renders as an `h3`.
descriptionReact.ReactNodeOptionalOptional supporting line beneath the title.
iconReact.ReactNodeOptionalOptional visual shown above the title.
actionReact.ReactNodeOptionalOptional action slot, usually a Button.
alignEmptyStateAlign | undefinedOptionalText alignment and horizontal placement of the block. Defaults to `center`.Source default: 'center'
padding0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefinedOptionalOuter padding token. Defaults to `32`.Source default: 32
classNamestring | undefinedOptional
styleReact.CSSProperties | undefinedOptional
testIdstring | undefinedOptionalOptional test selector.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

A full-region placeholder for when a whole area has nothing to show — a title, optional description and icon, and an optional recovery action.

When to use

Reach for EmptyState when an entire region is empty and you want to explain why and offer a way forward — a cleared queue, a search with no hits, a list before its first item. Pass an action (usually a Button) when there's a recovery path.

  • Content IS present and you're annotating it (a note or warning alongside real data)? Use Banner.
  • The region isn't empty, it's still loading? Use Skeleton to preserve the layout while it loads.

Component specification

$schema../../../specs/component-spec.schema.json
Parts
Id
root
Label
Root
Description
Column that stacks the icon, copy, and action with outer padding.
Required
true
Id
icon
Label
Icon
Description
Optional round visual above the title.
Id
copy
Label
Copy
Description
Title plus optional description.
Id
action
Label
Action
Description
Optional recovery control, usually a Button.
Allowed Design Choices
Variants
Placeholder
Label
Placeholder
Description
The single empty/no-results treatment.
Sizes
Alignments
Center
Label
Center
Description
Centers the block and its text.
Start
Label
Start
Description
Left-aligns the block and its text inside a panel.
Variants
Id
placeholder
Label
Placeholder
Description
Centered empty-region treatment.
Platforms
  • ios
  • android
  • web
SizesNone specified
Measurements
Id
content-gap
Label
Content gap
Kind
exact
Token
--cds-space-16
Value
16
Unit
px
Applies To
  • root
Id
icon-size
Label
Icon container size
Kind
exact
Token
--cds-size-56
Value
56
Unit
px
Applies To
  • icon
Id
default-padding
Label
Default outer padding
Kind
exact
Token
--cds-space-32
Value
32
Unit
px
Applies To
  • root
Notes
The padding prop selects a spacing step; 32 is the default.
Layout
Alignment
Icon, copy, and action stack vertically; alignment controls horizontal placement and text alignment.
Flow
A single column with a max-width copy block capped at 320.
Notes
  • Use Banner to annotate content that is present rather than a whole empty region.
Typography And Color
Typography
Label
Title
Description
Uses the h4 ramp.
Token
--cds-type-h4-size
Label
Description
Description
Uses the body ramp.
Token
--cds-type-body-size
Colors
Label
Title
Description
Primary text for the title.
Token
--cds-text-primary
Label
Description
Description
Secondary text for supporting copy and the icon.
Token
--cds-text-secondary
Label
Icon surface
Description
The icon sits on a raised surface disc.
Token
--cds-bg-surface
States
Id
center
Label
Centered
Description
Content centered on both the horizontal axis and text.
Id
start
Label
Start aligned
Description
Content left-aligned inside a panel.
Id
with-icon
Label
With icon
Description
Shows the round icon disc above the title.
Id
with-action
Label
With action
Description
Shows a recovery action below the copy.
Behavior
Label
Alignment
Description
Set align to center for standalone screens or start for in-panel placeholders.
Label
Recovery action
Description
Offer an action only when the user can meaningfully resolve the empty state.
Accessibility
Label
Heading
Description
The title renders as a heading so the empty region is announced.
Label
Actionable copy
Description
Describe the next step in the description rather than relying on the icon.
Content Adaptation
Label
Copy width
Description
The copy column caps its width so long descriptions stay readable.
Label
Optional slots
Description
Icon, description, and action each render only when provided.
Motion Haptics
Motion
Label
Static
Description
EmptyState does not animate on appearance.
Haptics
Label
No feedback
Description
The container requests no haptics; its action button owns any feedback.
Platform DifferencesNone specified
Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1