empty
Use the Empty component to display a empty state.
Philosophy
Empty states are opportunities, not dead ends. When there's no data to show, the Empty component turns a blank screen into a call to action. We structure it as header + content because every empty state needs two things: an explanation of why it's empty, and a path forward. The media slot (icon, avatar, illustration) adds emotional tone.
How It's Built
Installation
npx @gentleduck/cli add empty
npx @gentleduck/cli add empty
Usage
import {
Empty,
EmptyContent,
EmptyDescription,
EmptyHeader,
EmptyMedia,
EmptyTitle,
} from "@/components/ui/empty"import {
Empty,
EmptyContent,
EmptyDescription,
EmptyHeader,
EmptyMedia,
EmptyTitle,
} from "@/components/ui/empty"<Empty>
<EmptyHeader>
<EmptyMedia variant="icon">
<Icon />
</EmptyMedia>
</EmptyHeader>
<EmptyTitle>No data</EmptyTitle>
<EmptyDescription>No data found</EmptyDescription>
<EmptyContent>
<Button>Add data</Button>
</EmptyContent>
</Empty><Empty>
<EmptyHeader>
<EmptyMedia variant="icon">
<Icon />
</EmptyMedia>
</EmptyHeader>
<EmptyTitle>No data</EmptyTitle>
<EmptyDescription>No data found</EmptyDescription>
<EmptyContent>
<Button>Add data</Button>
</EmptyContent>
</Empty>Examples
Outline
Use the border utility class to create a outline empty state.
Background
Use the bg-* and bg-gradient-* utilities to add a background to the empty state.
Avatar
Use the EmptyMedia component to display an avatar in the empty state.
Avatar Group
Use the EmptyMedia component to display an avatar group in the empty state.
InputGroup
You can add an InputGroup component to the EmptyContent component.
Component Composition
API Reference
Empty
The main component of the empty state. Wraps the EmptyHeader and EmptyContent components.
| Prop | Type | Default | Description |
|---|---|---|---|
dir | 'ltr' | 'rtl' | -- | Text direction override. Resolved via useDirection (dir prop -> DirectionProvider -> 'ltr'). |
className | string | -- | Additional CSS classes |
children | React.ReactNode | -- | Empty state content |
...props | React.HTMLProps<HTMLDivElement> | -- | Additional props to spread to the content div |
EmptyHeader
The EmptyHeader component wraps the empty media, title, and description.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | -- | Additional CSS classes |
children | React.ReactNode | -- | Header content (media, title, description) |
...props | React.HTMLProps<HTMLDivElement> | -- | Additional props to spread to the content div |
EmptyMedia
Use the EmptyMedia component to display the media of the empty state such as an icon or an image. You can also use it to display other components such as an avatar.
| Prop | Type | Default | Description |
|---|---|---|---|
variant | 'default' | 'icon' | 'default' | Visual variant of the media container |
className | string | -- | Additional CSS classes |
children | React.ReactNode | -- | Media content (icon, avatar, image) |
...props | React.HTMLProps<HTMLDivElement> | -- | Additional props to spread to the content div |
EmptyTitle
Use the EmptyTitle component to display the title of the empty state.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | -- | Additional CSS classes |
children | React.ReactNode | -- | Title text |
...props | React.HTMLProps<HTMLDivElement> | -- | Additional props to spread to the content div |
EmptyDescription
Use the EmptyDescription component to display the description of the empty state.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | -- | Additional CSS classes |
children | React.ReactNode | -- | Description text |
...props | React.ComponentProps<'p'> | -- | Additional props to spread to the description element (renders as a div) |
EmptyContent
Use the EmptyContent component to display the content of the empty state such as a button, input or a link.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | -- | Additional CSS classes |
children | React.ReactNode | -- | Action content (buttons, links, inputs) |
...props | React.HTMLProps<HTMLDivElement> | -- | Additional props to spread to the content div |
RTL Support
Direction is resolved through the shared primitives direction module. Use a local dir="rtl" override when the component exposes it, or set DirectionProvider at app/root level for global RTL/LTR behavior.