Empty state components

Q: What sizes are available for empty states?

The size prop on the EmptyState root accepts "sm", "md" and "lg" and defaults to "lg". It flows through context to the title, description, spacing, EmptyState.Illustration, EmptyState.AvatarRow and EmptyState.AvatarGrid. EmptyState.FeaturedIcon renders at "xl" under a "lg" root and "lg" otherwise unless you set its own size, while EmptyState.Illustration only honors its own size when the root is "lg".

Q: How do I compose an empty state?

Nest the parts inside EmptyState: EmptyState.Header holds the visual, EmptyState.Content wraps EmptyState.Title and EmptyState.Description, and EmptyState.Footer holds your action buttons in a row. Every part also accepts a className for one-off adjustments.

Q: What visuals can I put in the empty state header?

Use EmptyState.FeaturedIcon (defaults to the SearchLg icon with color="gray" and theme="modern"), EmptyState.Illustration with type set to "cloud" (the default), "box", "documents" or "credit-card", or EmptyState.FileTypeIcon with a type such as "folder" (the default) and a theme of "solid" (the default), "default" or "gray".

Q: How do I change or remove the background pattern?

EmptyState.Header takes a pattern prop that accepts "circle" (the default), "square", "grid", "grid-check", or "none" to drop the pattern entirely. patternSize controls its scale with "sm", "md" (the default) or "lg".

Q: How do I show avatars in an empty state?

EmptyState.AvatarRadius, EmptyState.AvatarRow and EmptyState.AvatarGrid each take an avatars array of { src, alt? } objects. AvatarRadius places up to nine avatars on concentric rings, AvatarRow splits them into a left and right cluster around its children, and AvatarGrid splits them across two scrolling marquee rows.

Q: Will an empty state add extra headings or landmarks to my page?

Yes. EmptyState.Title renders an <h1> and EmptyState.Content renders a <main>, which suits a full-page empty state but duplicates both inside a page that already has them. Both spread your props onto the element, so <EmptyState.Title role="heading" aria-level={2}> demotes the heading and <EmptyState.Content role="presentation"> drops the landmark. The avatar decorations are aria-hidden, so keep the meaningful copy in the title and description.

Q: Does the animated avatar grid respect reduced motion?

Yes. The marquee rows in EmptyState.AvatarGrid are marked motion-reduce:animate-none, so the animation stops for users who have the reduced-motion preference enabled while the layout stays intact.

Powerful and customizable React empty state components built for modern applications and websites. These empty states are built using React Aria and styled with Tailwind CSS.

Empty state example

Get the code

No projects found

Your search “Landing page design” did not match any projects. Please try again.

Installation

You can add this empty states component using our CLI or manually:

CLI

Manual

npx untitledui@latest add empty-state

Empty states examples

Below are examples and variations of this empty states component:

Featured icon

Get the code

No projects found

Your search “Landing page design” did not match any projects. Please try again.

Illustration

Get the code

No projects found

Your search “Landing page design” did not match any projects. Please try again.

File icon

Get the code

No projects found

Your search “Landing page design” did not match any projects. Please try again.

Avatar radius

Get the code

No users found

Your search did not match any users.

Avatar row

Get the code

Invite your first user

Add your team members and external users.

Avatar grid

Get the code

Sorry, no results!

We couldn't find any apps or commands.
Please try again or browse all apps.

API reference

Import the parts and assemble them:

import { EmptyState } from "@/components/application/empty-state/empty-state";
 
<EmptyState>
    <EmptyState.Header>
        <EmptyState.FeaturedIcon />
    </EmptyState.Header>
 
    <EmptyState.Content>
        <EmptyState.Title />
        <EmptyState.Description />
    </EmptyState.Content>
 
    <EmptyState.Footer />
</EmptyState>

EmptyState

Renders a <div> element.

EmptyState props
Prop	Type	Default	Description
`size`	`"sm""md""lg"`	`"lg"`	Scales the whole empty state — the header icon or illustration, the heading and description type, the avatar decorations, and the spacing between the sections. Read by every sub-component through context.

Also accepts all standard HTML attributes, all aria-* attributes, all standard React DOM event handlers.

EmptyState.AvatarGrid

Renders a <div> element.

EmptyState.AvatarGrid props
Prop	Type	Default	Description
`avatars`	`{ src: string; alt?: string; }[]`	`[]`	Avatars split into two marquee rows that scroll in opposite directions behind the empty state. The first half of the list fills the top row and the rest the bottom row, each repeated to loop seamlessly.

Also accepts all standard HTML attributes, all aria-* attributes, all standard React DOM event handlers.

EmptyState.AvatarRadius

Renders a <div> element.

EmptyState.AvatarRadius props
Prop	Type	Default	Description
`avatars`	`{ src: string; alt?: string; }[]`	`[]`	Avatars scattered across the concentric rings behind the empty state. Each one takes the next predefined ring and angle, so at most nine are drawn and any extras are ignored.

Also accepts all standard HTML attributes, all aria-* attributes, all standard React DOM event handlers.

EmptyState.AvatarRow

Renders a <div> element.

EmptyState.AvatarRow props
Prop	Type	Default	Description
`avatars`	`{ src: string; alt?: string; }[]`	`[]`	Avatars fanned out either side of the children, growing towards the centre. The first few fill the left group and the next few the right — three or four per side depending on the root size — and any extras are ignored.
`children`	`ReactNode`	—	Content placed between the two avatar groups, typically the empty state's featured icon or illustration.

Also accepts all standard HTML attributes, all aria-* attributes, all standard React DOM event handlers.

EmptyState.Content

Renders a <main> element.

Also accepts all standard HTML attributes, all aria-* attributes, all standard React DOM event handlers.

EmptyState.Description

Renders a <p> element.

Also accepts all standard HTML attributes, all aria-* attributes, all standard React DOM event handlers.

EmptyState.FeaturedIcon

Renders FeaturedIcon.

EmptyState.FeaturedIcon props
Prop	Type	Default	Description
`children`	`ReactNode`	—	Extra content rendered inside the wrapper, alongside the icon.
`className`	`string`	—	The class name applied to the wrapper.
`icon`	`ReactNode \| FC<{ className?: string; }>`	`SearchLg`	The icon to display. Accepts a component reference or a rendered element.
`size`	`"sm""md""lg""xl"`	—	Controls the dimensions of the wrapper and the icon inside it.
`color`	`"brand""gray""success""warning""error"`	`"gray"`	The semantic color used for the background, icon and border of the current theme. The `modern` and `modern-neue` themes are only styled for `gray`.
`theme`	`"light""gradient""dark""outline""modern""modern-neue"`	`"modern"`	The visual treatment of the icon container, from a subtle tinted circle to a solid, outlined or skeuomorphic surface.

EmptyState.FileTypeIcon

Renders a <div> element.

EmptyState.FileTypeIcon props
Prop	Type	Default	Description
`type`	`FileType`	`"folder"`	Which file type the icon depicts, forwarded to `FileIcon` from `@untitledui/file-icons`.
`theme`	`"gray""default""solid"`	`"solid"`	Drawing style of the file icon, forwarded to `FileIcon` as its `variant`.

Also accepts all standard HTML attributes, all aria-* attributes, all standard React DOM event handlers.

EmptyState.Header

Renders a <header> element.

EmptyState.Header props
Prop	Type	Default	Description
`pattern`	`"none""circle""square""grid""grid-check"`	`"circle"`	Decorative background pattern drawn behind the header's icon or illustration and centred on it. Pass `"none"` to render the header without a pattern.
`patternSize`	`"sm""md""lg"`	`"md"`	How far the decorative background pattern extends behind the header content.

Also accepts all standard HTML attributes, all aria-* attributes, all standard React DOM event handlers.

EmptyState.Illustration

Renders Illustration.

EmptyState.Illustration props
Prop	Type	Default	Description
`size`	`"sm""md""lg"`	`"lg"`	The overall scale of the illustration, which also selects the background pattern drawn behind it.
`svgClassName`	`string`	—	Classes applied to the inline `svg` itself, for overriding its stroke or fill.
`childrenClassName`	`string`	—	Classes applied to the badge that holds `children`, the icon floating over the illustration.
`type`	`"box""cloud""documents""credit-card"`	`"cloud"`	Which illustration to draw.

Also accepts all standard HTML attributes, all aria-* attributes, all standard React DOM event handlers.

EmptyState.Title

Renders a <h1> element.

Also accepts all standard HTML attributes, all aria-* attributes, all standard React DOM event handlers.

FAQs

Please refer to our frequently asked questions page for more.

The size prop on the EmptyState root accepts "sm", "md" and "lg" and defaults to "lg". It flows through context to the title, description, spacing, EmptyState.Illustration, EmptyState.AvatarRow and EmptyState.AvatarGrid. EmptyState.FeaturedIcon renders at "xl" under a "lg" root and "lg" otherwise unless you set its own size, while EmptyState.Illustration only honors its own size when the root is "lg".

Nest the parts inside EmptyState: EmptyState.Header holds the visual, EmptyState.Content wraps EmptyState.Title and EmptyState.Description, and EmptyState.Footer holds your action buttons in a row. Every part also accepts a className for one-off adjustments.

Use EmptyState.FeaturedIcon (defaults to the SearchLg icon with color="gray" and theme="modern"), EmptyState.Illustration with type set to "cloud" (the default), "box", "documents" or "credit-card", or EmptyState.FileTypeIcon with a type such as "folder" (the default) and a theme of "solid" (the default), "default" or "gray".

EmptyState.Header takes a pattern prop that accepts "circle" (the default), "square", "grid", "grid-check", or "none" to drop the pattern entirely. patternSize controls its scale with "sm", "md" (the default) or "lg".

EmptyState.AvatarRadius, EmptyState.AvatarRow and EmptyState.AvatarGrid each take an avatars array of { src, alt? } objects. AvatarRadius places up to nine avatars on concentric rings, AvatarRow splits them into a left and right cluster around its children, and AvatarGrid splits them across two scrolling marquee rows.

Yes. EmptyState.Title renders an <h1> and EmptyState.Content renders a <main>, which suits a full-page empty state but duplicates both inside a page that already has them. Both spread your props onto the element, so <EmptyState.Title role="heading" aria-level={2}> demotes the heading and <EmptyState.Content role="presentation"> drops the landmark. The avatar decorations are aria-hidden, so keep the meaningful copy in the title and description.

Yes. The marquee rows in EmptyState.AvatarGrid are marked motion-reduce:animate-none, so the animation stops for users who have the reduced-motion preference enabled while the layout stays intact.

Date pickers File uploaders