Empty State

Compound primitive for centered no-content messaging with icon, title, description, and actions.

Overview

EmptyState is the shared compound primitive for surfaces that have no data yet, no results, or no configured content — but are not in an error state.

It is the visual counterpart to ErrorState:

Primitive	Use when
`EmptyState`	The surface is healthy but empty, unconfigured, or awaiting first use
`ErrorState`	The surface failed to load or is blocked

This page documents the primitive. See the data-display pattern for when to use empty states in tables, lists, and panels.

Basic Composition

import { EmptyState } from '@fsai/shared-ui';

<EmptyState className="py-8">
  <EmptyState.Icon icon="UserGroupOutlined" />
  <EmptyState.Title>No team members yet</EmptyState.Title>
  <EmptyState.Description>
    Invite colleagues to collaborate on this workspace.
  </EmptyState.Description>
  <EmptyState.Actions>
    <EmptyState.Action role="button" variant="primary" onClick={handleInvite}>
      Invite Member
    </EmptyState.Action>
  </EmptyState.Actions>
</EmptyState>

Description Only

For compact inline empty messaging, title and actions are optional:

<EmptyState className="py-8">
  <EmptyState.Icon icon="Key" />
  <EmptyState.Description>No API keys yet.</EmptyState.Description>
</EmptyState>

This is the pattern used in organization settings pages.

Animated Icon

Set animated on EmptyState.Icon to breathe the concentric background rings — useful for in-progress or searching states:

<EmptyState>
  <EmptyState.Icon icon="SearchMagnifyingGlass" animated />
  <EmptyState.Title>Searching...</EmptyState.Title>
</EmptyState>

Compound API

Part	Purpose
`EmptyState`	Root centered stack container.
`EmptyState.Icon`	Decorative icon with concentric ring background.
`EmptyState.Title`	Primary heading.
`EmptyState.Description`	Supporting explanation text.
`EmptyState.Actions`	Horizontal action row.
`EmptyState.Action`	Shared `Button`-based action.

Props

`EmptyState`

Prop	Type	Description
`children`	`ReactNode`	Required. Empty state content tree.
`className`	`string`	Additional layout classes. Often `py-8` for compact surfaces.

`EmptyState.Icon`

Prop	Type	Default	Description
`icon`	`IconName \| ComponentType`	`TableSpreadsheetOutlined`	Main icon.
`animated`	`boolean`	`false`	Animates the concentric ring background.
`className`	`string`	—	Additional wrapper classes.

`EmptyState.Title`

Prop	Type	Description
`children`	`ReactNode`	Required. Title content.
`className`	`string`	—

`EmptyState.Description`

Prop	Type	Description
`children`	`ReactNode`	Required. Description content.
`className`	`string`	—

`EmptyState.Actions` / `EmptyState.Action`

EmptyState.Action forwards shared ButtonProps with variant="secondary" and size="md" defaults.

When To Use Raw `EmptyState`

Reach for raw composition when:

a list, panel, or settings section has no items yet
a feature needs onboarding-oriented messaging with a primary action
the surface is healthy but unconfigured

Prefer higher-level empty handling when available:

DataTable emptyState prop for collection-level emptiness
Picker.Empty for dropdown empty states
InlineEntityManager.HelperText for compact inline emptiness

Brand Dashboard And Shared Usage

Pattern	Path	Notes
Organization settings	`fsai/apps/brand-dashboard/src/pages/OrganizationSettings/OrganizationSettingsTeam/OrganizationSettingsTeam.tsx`	Compact description-only empty states.
Saved views menu	`fsai/packages/shared-ui/src/components/DataTable/toolbar/SavedViewsMenu.tsx`	Empty saved views list.
Post analytics	`fsai/packages/shared-ui/src/modules/socials/components/PostSets/PostComposer/components/PostAnalyticsEmptyState.tsx`	Full composition with title, description, and action.
Applicant tickets	`fsai/apps/applicant-portal/src/pages/MyTickets/MyTickets.tsx`	Consumer-facing empty ticket list.

Important Conventions

Do not use EmptyState for error or failure messaging — use ErrorState or ErrorGuard.
Do not use EmptyState as a loading placeholder — use Skeleton or Spinner.
Keep actions forward-looking: create, invite, configure, or get started.
Adjust vertical padding with className to match the surrounding surface density.

Guidelines

Do use EmptyState for healthy but empty surfaces
Do include a primary action when the user can resolve the emptiness
Do use animated on the icon for searching or in-progress empty states
Don't use EmptyState for blocked or failed surfaces
Don't use ErrorState when the content is simply empty

Empty State

On this page