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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthInstallation
Import Empty and subcomponents from @/components/kamod-ui/empty (EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent).
pnpm add @kamod-ch/uiCopy 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 { 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.
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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthLegacy 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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthLegacy + 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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthOutline
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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthBackground
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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthAvatar
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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthAvatar 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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthInput 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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthProps 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.
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
? 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.Empty
EmptyProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
description | Legacy: description line.
|
title | Legacy: render title inside dashed card (use EmptyTitle when composing).
|
EmptyContent
EmptyContentProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
EmptyDescription
EmptyDescriptionProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
EmptyHeader
EmptyHeaderProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
EmptyMedia
EmptyMediaProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
variant | Configure
|
EmptyTitle
EmptyTitleProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
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 fieldsEmptyPropsEmpty.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 fieldEmptyContentPropsEmptyContent.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 fieldEmptyDescriptionPropsEmptyDescription.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 fieldEmptyHeaderPropsEmptyHeader.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 fieldEmptyMediaPropsEmptyMedia.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 fieldEmptyTitlePropsEmptyTitle.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
DeclarationEmptyRootVariantsempty-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.
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.