Your next page is taking shape...

Opening Your Next Page…

Loading the guide and preparing its examples for you to explore. The page will appear here automatically when it’s ready, so you can keep this view open without refreshing.

Made for Preact. Built to be yours.

Status & Feedback

Empty

Empty states for no data — composable EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent (shadcn-aligned). Legacy title/description props still work. Explain what is happening, what changed and what someone can do next. Pair visual status with language that still makes sense without its color. Import it from @/components/kamod-ui/empty.

Source · Design reference · API reference · Theming · Styles


Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Installation

Import Empty and subcomponents from @/components/kamod-ui/empty (EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent).

Install PackagesTerminal
pnpm add @kamod-ch/ui

Copy an example with @kamod-ch/ui or the matching @kamod-ch/ui/… subpath. The code block switches between those two installs. Connect The Global Theme CSS and Tailwind Source Detection before your first render.

Usage

Compose media, title, and description in EmptyHeader; primary actions in EmptyContent. Add border or background via class on Empty. Legacy API: pass title and description props for quick dashed cards.

Import SetupTypeScript
import { Empty } from "@kamod-ch/ui";

Choose a complete composition from the examples below; required child components and props vary by pattern.

Component Examples & Variants

Explore Empty in Different Contexts, from the starting pattern to the compositions below. Begin with Demo, then compare the examples that match your content, state and layout. These are working patterns to adapt, not a list of interchangeable variant values: check the API Reference before using a prop or combining behaviors. Look at the surrounding labels, supporting text and spacing as well as the component itself.

Read the Result and Its Implementation Together. Use each showcase’s Code view to inspect imports and composition, or its Prompt view to prepare a setup or adaptation brief. Try the narrow preview and local theme controls before connecting real data, and use Reset to return an example to its initial state. Keep layout changes in class utilities where appropriate; follow the Component Styles Guide for hierarchy and the Theming Guide for shared surfaces and colors. The Accessibility Notes explain what to preserve when making those changes.

Demo

Explain the Absence and Offer a Useful Next Step. Compose EmptyMedia, a title, a description and a useful action to explain why a region has no content yet. The footer link can offer secondary guidance without competing with the main step toward creating or finding content.

Use one clear primary action and keep the footer link secondary; an empty state should reduce uncertainty rather than simply fill unused space.

src/components/EmptyExample.tsx25 lines
import { Button, Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "@kamod-ch/ui";
import { ArrowUpRight, Folder } from "lucide-preact";

export const Example = () => (
  <Empty>
    <EmptyHeader>
      <EmptyMedia variant="icon">
        <Folder aria-hidden />
      </EmptyMedia>
      <EmptyTitle>No Projects Yet</EmptyTitle>
      <EmptyDescription>
        You haven't created any projects yet. Get started by creating your first project.
      </EmptyDescription>
    </EmptyHeader>
    <EmptyContent class="flex-row flex-wrap justify-center gap-2">
      <Button>Create Project</Button>
      <Button variant="outline">Import Project</Button>
    </EmptyContent>
    <Button variant="link" asChild class="text-muted-foreground" size="sm">
      <a href="#">
        Learn More <ArrowUpRight class="size-4" aria-hidden />
      </a>
    </Button>
  </Empty>
);

Usage

Start with the Message before Adding Decoration. Start with the empty-state title and description before adding decoration or controls. This establishes what is missing and why, giving the surrounding screen a useful explanation even when no records are available.

Distinguish a genuinely empty collection from loading or failure, and add media only when it reinforces the purpose rather than delaying the first useful instruction.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Legacy Props

Use the Shorthand for Straightforward Messages. Use the legacy title and description props when a compact empty-state composition is sufficient. The dashed surface groups the explanation, and any children can supply the next step beneath that message.

Choose the compound structure when the layout needs richer media or multiple regions, and avoid mixing both approaches without checking where content renders.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Legacy + Action

Place the Recovery Action after Its Explanation. Add a meaningful action as children of the legacy empty-state composition. It renders after the description, so the reader first learns what happened and then encounters the control that can change the situation.

Make the action specific to the state, such as creating the first item or clearing a filter, rather than using an unexplained generic “Continue”.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Outline

Mark the Boundary of a Missing Collection. Add border border-dashed to Empty when the missing content needs a clearly defined region. The outline gives the placeholder a boundary while leaving the message and recovery action responsible for explaining its purpose.

Keep the surface secondary and the instruction readable; the border alone should not imply that users can drag files into it unless that behavior exists.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Background

Separate the Message from the Surrounding Page. Use a muted background and a deliberate panel height to reserve space for an empty region. This keeps the layout recognizable before data arrives without presenting an empty surface as if it were a loading skeleton.

Avoid fixing an excessive height merely to fill space, and check that the message still feels connected to the controls that produced the empty result.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Avatar

Add a Human Cue Where It Fits the Task. Place an Avatar inside the default EmptyMedia treatment when the message concerns a person or account. The larger media region identifies the context while the title explains the missing connection or content.

Keep identity text available and avoid using an unexplained portrait as the only indication of who the empty state concerns.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Avatar Group

Suggest Collaboration without Implying Real Membership. Compose an avatar group inside EmptyMedia when the empty state concerns collaboration or membership. The people-related visual establishes context, while the description should still explain why the actual list or activity is absent.

Keep the message and invitation action primary, and make additional counts or identities accurate when using live data.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Input Group

Offer a Direct Way to Recover Results. Put a search control inside EmptyContent when changing the query is a useful recovery path. Input Group keeps the field and its action together without replacing the explanation of the empty result.

Keep the field labeled, preserve the current search text, and distinguish no matches from an empty dataset that searching cannot fix.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width
API reference

Props and Data

Configure Empty using the contracts below. Read the documented options alongside the Source Definitions to understand which values your application supplies and which details the component owns. Start with a prop or helper, then follow its type link to inspect the declaration without leaving the page.

Props, slots and variants for this component.

API reference
Your API, from source

Type cards are extracted from this checkout’s TypeScript source at build time. Props inherited through HTMLAttributes, Omit or variant helpers remain references in those declarations; their fields are not flattened here. Match the reference to your installed version, and check a package’s exports before writing an import type. A type exported by a source file is not necessarily re-exported by @kamod-ch/ui.

Component Props

Read each option with its owning component. The
marker identifies required fields verified in that declaration. A ? means a field can be omitted; it does not promise a fallback value. Existing documented defaults remain alongside the descriptions. For callbacks, check the argument and return types before connecting your own state or services.
@kamod-ch/ui/empty3.3 KB min · 1.0 KB gzipSignals: none

Empty

EmptyProps

Empty documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildEmptyProps

Configure children for Empty. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>EmptyProps

Configure class for Empty. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
description
ComponentChild[] | ComponentChildEmptyProps

Legacy: description line.

Default
—
title
((string | SignalLike<string | undefined>) & (string | number | bigint | boolean | object | ComponentChild[] | VNode<any> | null))EmptyProps

Legacy: render title inside dashed card (use EmptyTitle when composing).

Default
—

EmptyContent

EmptyContentProps

EmptyContent documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildEmptyContentProps

Configure children for EmptyContent. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>EmptyContentProps

Configure class for EmptyContent. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

EmptyDescription

EmptyDescriptionProps

EmptyDescription documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildEmptyDescriptionProps

Configure children for EmptyDescription. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>EmptyDescriptionProps

Configure class for EmptyDescription. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

EmptyHeader

EmptyHeaderProps

EmptyHeader documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildEmptyHeaderProps

Configure children for EmptyHeader. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>EmptyHeaderProps

Configure class for EmptyHeader. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

EmptyMedia

EmptyMediaProps

EmptyMedia documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildEmptyMediaProps

Configure children for EmptyMedia. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>EmptyMediaProps

Configure class for EmptyMedia. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
variant
anyEmptyMediaProps

Configure variant for EmptyMedia. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

EmptyTitle

EmptyTitleProps

EmptyTitle documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildEmptyTitleProps

Configure children for EmptyTitle. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>EmptyTitleProps

Configure class for EmptyTitle. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

Data Type Reference

Expand a card to inspect and copy the exact declaration. The code header identifies its repository file; follow imported or inherited types in the Implementation Source when you need the complete dependency chain. Required-field summaries cover fields declared directly in that type. Source-only helpers and inferred schema outputs describe the local implementation, not additional props you can pass to every component.

Empty Props

3 declared fields
EmptyProps
Exported Source Declaration from Empty.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of EmptyProps before adapting it.

EmptyContent Props

1 declared field
EmptyContentProps
Exported Source Declaration from EmptyContent.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of EmptyContentProps before adapting it.

EmptyDescription Props

1 declared field
EmptyDescriptionProps
Exported Source Declaration from EmptyDescription.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of EmptyDescriptionProps before adapting it.

EmptyHeader Props

1 declared field
EmptyHeaderProps
Exported Source Declaration from EmptyHeader.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of EmptyHeaderProps before adapting it.

EmptyMedia Props

1 declared field
EmptyMediaProps
Exported Source Declaration from EmptyMedia.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of EmptyMediaProps before adapting it.

EmptyTitle Props

1 declared field
EmptyTitleProps
Exported Source Declaration from EmptyTitle.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of EmptyTitleProps before adapting it.

EmptyRootVariants

Declaration
EmptyRootVariants
Exported Source Declaration from empty-variants.ts. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of EmptyRootVariants before adapting it.

Accessibility

Empty supplies composition for a title, description, media and actions. It does not infer why content is absent or automatically announce a changed result set. Heading semantics should be checked in the chosen composition rather than inferred from a title component's name.

Take the Next Useful Step

You have the pieces. Put them into one real interaction, keep its state in one place, and check the result with the content your application will actually show.

Connect the Foundation

Return to Choose and Compose Components to connect this reference to a working screen. Keep global CSS in one entrypoint and import only the components that screen needs.

Build the Surrounding Screen

Find a neighboring interaction in the Component Library, or start with a complete Block. Replace sample content and destinations before refining the layout; a local class change can stay with the composition.

Make the Result Hold Up

Use shared theme roles for changes that belong everywhere. Then review the whole journey: keyboard focus, long labels, narrow screens and a clear way to recover when something fails.

Keep a link to the source and note your intentional changes. Your next edit should begin with a clear decision, not another search.