## Overview [#overview]
The **EmptyState** component provides a consistent way to communicate that a section has no content to display. By default it fills the available parent space, centers its content, and renders a solid surface shell. Use `variant="ghost"` when the parent already owns the surrounding surface, and use `variant="overlay"` when the empty state should sit above existing content.
## Usage [#usage]
```tsx
import {
EmptyState,
EmptyStateDescription,
EmptyStateHeading,
EmptyStateMedia,
EmptyStateTitle,
} from "@tilt-legal/cubitt-components/primitives";
import { Inbox } from "@tilt-legal/cubitt-icons/ui/outline";
```
```tsx
No projects found
Create your first project to get started with your workflow.
```
## Examples [#examples]
### Ghost [#ghost]
Use `variant="ghost"` when the parent already provides the border, background, or padding.
```tsx
import {
EmptyState,
EmptyStateDescription,
EmptyStateHeading,
EmptyStateMedia,
EmptyStateTitle,
} from "@tilt-legal/cubitt-components/primitives";
import { Folder } from "@tilt-legal/cubitt-icons/ui/outline";
No folders
Create a folder to organize your files.
```
### Overlay [#overlay]
Use `variant="overlay"` when the empty state should sit on top of existing content, such as a table with skeleton rows.
```tsx
import {
EmptyState,
EmptyStateDescription,
EmptyStateHeading,
EmptyStateMedia,
EmptyStateTitle,
Skeleton,
Table,
TableBody,
TableCell,
TableHead,
TableHeader,
TableRow,
} from "@tilt-legal/cubitt-components/primitives";
import { Magnifier } from "@tilt-legal/cubitt-icons/ui/outline";
No results
Try adjusting your filters.
NameDescriptionStatusActions
```
### With Action Button [#with-action-button]
Use `EmptyStateAction` to add a call-to-action inside the empty state.
```tsx
import {
Button,
EmptyState,
EmptyStateAction,
EmptyStateDescription,
EmptyStateHeading,
EmptyStateMedia,
EmptyStateTitle,
} from "@tilt-legal/cubitt-components/primitives";
import { File, Plus } from "@tilt-legal/cubitt-icons/ui/outline";
No documents
Upload or create your first document to get started.
```
### Error State [#error-state]
Set `error` on `EmptyState` to apply error styling to `EmptyStateMedia` and `EmptyStateTitle`.
```tsx
import {
Button,
EmptyState,
EmptyStateAction,
EmptyStateDescription,
EmptyStateHeading,
EmptyStateMedia,
EmptyStateTitle,
} from "@tilt-legal/cubitt-components/primitives";
import {
RefreshAnticlockwise,
TriangleWarning,
} from "@tilt-legal/cubitt-icons/ui/outline";
Something went wrong
We couldn't load your data. Please try again.
```
## API Reference [#api-reference]
### EmptyState [#emptystate]
The root container component. By default it fills the available parent space with centered content and generous padding.
| Prop | Type | Default | Description |
| ----------- | ----------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `variant` | `"default" \| "ghost" \| "overlay"` | `"default"` | `default` renders the solid shell, `ghost` removes shell styling, and `overlay` positions the state absolutely with a gradient background |
| `error` | `boolean` | `false` | Enables error styling for `EmptyStateMedia` and `EmptyStateTitle` |
| `className` | `string` | - | Additional CSS classes. Use this to override the default fill, spacing, or surface styling |
| `children` | `React.ReactNode` | - | Child components |
### EmptyStateMedia [#emptystatemedia]
Container for the icon with a circular background. Automatically applies error styling when the parent has `error`.
| Prop | Type | Default | Description |
| ----------- | --------------------------- | ----------- | --------------------------------------- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Controls the media circle and icon size |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Icon element |
### EmptyStateHeading [#emptystateheading]
Container for the title and description.
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | ---------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Title and description |
### EmptyStateTitle [#emptystatetitle]
The title text. Automatically applies error styling when the parent has `error`.
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | ---------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Title content |
### EmptyStateDescription [#emptystatedescription]
The description text.
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | ---------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Description content |
### EmptyStateAction [#emptystateaction]
Container for action buttons.
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | ---------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Button element(s) |
## Design Guidelines [#design-guidelines]
### When to Use [#when-to-use]
* Empty lists, tables, or grids
* Search results with no matches
* Error states when data fails to load
* First-time user experiences
### Best Practices [#best-practices]
* Always provide a clear, actionable title
* Include a helpful description explaining what the user can do
* Use `variant="ghost"` when a parent container already owns the surrounding shell
* Use `variant="overlay"` when content should stay mounted underneath
* When appropriate, include an action button to help users resolve the empty state
* Use the error state for failed data loading, not for validation errors