Empty State - HapplyUI

A centered placeholder for empty listing pages. The Icon subcomponent renders a stroke KeyIcon with soft-400 text and a deep shadow. Supports an optional dashed border, three sizes, and a composed shorthand.

Installation

bunx @happlyui/cli@latest add empty-state

Dependencies

Registry dependencies

These are automatically installed when you add this component.

tv
key-icon

Usage

import * as EmptyState from "@/components/ui/empty-state"

<EmptyState.Root bordered>
  <EmptyState.Icon icon={<RiInboxLine />} />
  <EmptyState.Description>
    You don't have any items yet
  </EmptyState.Description>
</EmptyState.Root>

Examples

Default

Bordered empty state with icon, description, and an action button.

You don't have any folder or file uploaded yet

<EmptyState.Root bordered>
  <EmptyState.Icon icon={<RiUploadCloud2Line />} />
  <EmptyState.Description>
    You don't have any folder or file uploaded yet
  </EmptyState.Description>
  <EmptyState.Actions>
    <Button.Root size="xsmall" variant="neutral" mode="stroke">
      <Button.Icon as={RiAddLine} />
      Add your first resource
    </Button.Root>
  </EmptyState.Actions>
</EmptyState.Root>

With Title

Empty state with both a title and description.

No items yet

Items you create will appear here. Get started by adding your first one.

<EmptyState.Root bordered>
  <EmptyState.Icon icon={<RiInboxLine />} />
  <EmptyState.Title>No items yet</EmptyState.Title>
  <EmptyState.Description>Get started by adding your first one.</EmptyState.Description>
</EmptyState.Root>

Search — No Results

Empty state for search results with no action button.

No results found

We couldn't find anything matching your search. Try different keywords or remove some filters.

<EmptyState.Root bordered>
  <EmptyState.Icon icon={<RiSearchLine />} />
  <EmptyState.Title>No results found</EmptyState.Title>
  <EmptyState.Description>Try different keywords or remove some filters.</EmptyState.Description>
</EmptyState.Root>

No Files

File upload empty state with a single action.

No files uploaded

Drag and drop files here, or click the button below to upload.

Multiple Actions

Secondary stroke button paired with a primary filled button.

No team members

Invite people to collaborate on this project together.

Unbounded

Without dashed border — useful inside existing cards or tables.

No upcoming events

Your schedule is clear. Enjoy the free time or plan something new.

Sizes

Three sizes: sm, md (default), and lg. Icon size scales automatically.

Empty state — sm

This is the sm size variant of the empty state component.

Empty state — md

This is the md size variant of the empty state component.

Empty state — lg

This is the lg size variant of the empty state component.

<EmptyState.Root size="lg" bordered>
  <EmptyState.Icon size="xl" icon={<RiFileList3Line />} />
  ...
</EmptyState.Root>

Composed

Shorthand version — icon size auto-maps from the root size.

You don't have any folder or file uploaded yet

<EmptyState.Composed
  bordered
  icon={<RiUploadCloud2Line />}
  description="You don't have any items yet"
  actions={<Button.Root size="xsmall" variant="neutral" mode="stroke">Add item</Button.Root>}
/>

API Reference

EmptyState.Root

Centered flex container for the empty state content.

Prop	Type	Default	Description
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Controls padding and text sizes
`bordered`	`boolean`	`false`	Adds a dashed border container

EmptyState.Icon

Renders a stroke KeyIcon with text-text-soft-400 and shadow-regular-deep.

Prop	Type	Default	Description
`icon`	`React.ReactNode`	-	The icon element to display
`size`	`'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`	`'lg'`	KeyIcon size

EmptyState.Title

Optional heading text in text-sub-600.

Prop	Type	Default	Description

EmptyState.Description

Subdued description text in text-soft-400, max-width constrained.

Prop	Type	Default	Description

EmptyState.Actions

Horizontal flex container for action buttons.

Prop	Type	Default	Description

EmptyState.Composed

Opinionated shorthand. Icon size auto-maps from root size (sm→md, md→lg, lg→xl). Accepts all Root props.

Prop	Type	Default	Description
`icon`	`React.ReactNode`	-	Icon element rendered inside EmptyState.Icon
`title`	`string`	-	Heading text
`description`	`string`	-	Description text
`actions`	`React.ReactNode`	-	Action buttons