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.

Composition & Layout

Item

Item composes media, title, description, and actions in a flexible row — aligned with shadcn/ui item patterns. Build a clear hierarchy with reusable structure, consistent spacing and semantic surfaces. Keep layout decisions close to the content they organize. Import it from @/components/kamod-ui/item.

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 Item and subcomponents (ItemMedia, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemGroup, …) from @/components/kamod-ui/item.

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

Use variant (default, outline, muted) and size (default, sm, xs). Use asChild to render a link or other host with item styles. Prefer Field when the row wraps a form control (input, checkbox, select); use Item for read-only rows, lists, and actions.

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

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

Component Examples & Variants

Explore Item in Different Contexts, from the starting pattern to the compositions below. Begin with Basic Patterns, 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.

Basic Patterns

Choose the Interaction before the Surface. Compose outlined items with supporting text and actions, then compare a compact item rendered as a link through asChild. The examples distinguish a row containing actions from a row whose entire surface is one destination.

Keep those patterns distinct so users know where clicking will lead, and avoid nesting independent buttons inside an anchor that already makes the entire row interactive.

src/components/ItemExample.tsx29 lines
import { Button, Item, ItemActions, ItemContent, ItemDescription, ItemMedia, ItemTitle } from "@kamod-ch/ui";
import { BadgeCheck, ChevronRight } from "lucide-preact";

export const Example = () => (
  <div class="flex w-full max-w-md flex-col gap-6">
    <Item variant="outline">
      <ItemContent>
        <ItemTitle>Basic Item</ItemTitle>
        <ItemDescription>A simple item with title and description.</ItemDescription>
      </ItemContent>
      <ItemActions>
        <Button variant="outline" size="sm">Action</Button>
      </ItemActions>
    </Item>
    <Item variant="outline" size="sm" asChild>
      <a href="#item-demo">
        <ItemMedia>
          <BadgeCheck class="size-5" />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Your profile has been verified.</ItemTitle>
        </ItemContent>
        <ItemActions>
          <ChevronRight class="size-4" />
        </ItemActions>
      </a>
    </Item>
  </div>
);

Usage

Give Each Region a Clear Role. Use ItemMedia, ItemTitle, ItemDescription and an action to structure a single list entry. Each region has a clear role, keeping the subject and its explanation readable before the user encounters the associated control.

Keep the primary label readable at narrow widths, and omit regions that add no useful information rather than filling every slot by default.

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

Variants

Use Surface Weight to Establish Hierarchy. Choose the transparent default, outlined or muted item treatment according to how much separation the list needs. The variant changes the surface while the title, description and actions retain the same structural relationship.

Keep equivalent items styled consistently, and preserve focus and selected-state distinctions when the row is interactive.

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

Sizes

Increase Density without Losing the Title. Use size="sm" or size="xs" for denser item collections where the content remains concise. The size coordinates padding and gaps, letting related rows share one rhythm instead of individually tightened spacing.

Check the longest realistic label and media combination before reducing size, and avoid using a dense variant for content that needs several explanatory lines.

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

Icon Media

Use the Media Tile as a Recognition Cue. Set variant="icon" on ItemMedia to place a symbol in a consistent muted tile. This gives neighboring items a common visual anchor even when their individual icon shapes have different proportions.

Keep decorative symbols hidden from assistive technology and avoid choosing different icons merely for variety when the items represent the same kind of record.

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 Media

Connect the Row to an Identifiable Person. Use the default ItemMedia treatment for an Avatar or a custom identity composition. The media identifies the subject, leaving the title and description to explain the row's purpose and supporting information.

Plan for image failure and initials fallback, and keep any status badge understandable in text when availability or identity matters to the action at the end of the row.

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

Image Media

Keep Thumbnails Consistent Across a Collection. Use the image media variant for bounded cover artwork beside item text. Combine ItemGroup and asChild links when the collection represents navigable resources, keeping the image and label part of the same destination.

Preserve a readable text title and make the destination explicit when using asChild; compare Image for smaller media compositions.

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

Group

Present Related Records as a Coherent List. Wrap related rows in ItemGroup to express a list and coordinate their visual arrangement. Outlined items can remain distinct, while optional separators provide another way to establish boundaries in a denser composition.

Use stable keys for dynamic records and keep separators secondary; a list should remain understandable when descriptions wrap or some rows have actions and others do not.

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

Separator

Create Rhythm without Boxing Every Row. Insert ItemSeparator between neighboring rows when a shared list needs quiet visual divisions. The horizontal rule follows the item group's rhythm without requiring each row to carry a complete card-like outline.

Match the surrounding spacing and avoid redundant borders when using outlined items; separators should clarify grouping rather than dominate it.

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

Inside Dropdown

Keep Rich Menu Rows Compact and Selectable. Use an extra-small Item at full width inside DropdownItem for richer menu content. Keep the menu item's activation behavior clear, avoiding nested independent actions inside a row that already behaves as a command.

Preserve the dropdown's keyboard semantics and avoid adding nested focusable controls that compete with row selection.

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 Item 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/item11.0 KB min · 3.0 KB gzipSignals: none

Item

ItemProps

Item documented props
Prop / typeDescription
asChild
booleanItemProps

Configure asChild for Item. Compare its accepted type with the Usage Guidance before supplying a value.

Default
false
children
ComponentChild[] | ComponentChildItemProps

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

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

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

Default
—
size
"default" | "sm" | "xs"ItemProps

Configure size for Item. Compare its accepted type with the Usage Guidance before supplying a value.

Default
"default"
variant
"default" | "outline" | "muted"ItemProps

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

Default
"default"

ItemActions

ItemActionsProps

ItemActions documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildItemActionsProps

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

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

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

Default
—

ItemContent

ItemContentProps

ItemContent documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildItemContentProps

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

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

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

Default
—

ItemDescription

ItemDescriptionProps

ItemDescription documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildItemDescriptionProps

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

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

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

Default
—

ItemFooter

ItemFooterProps

ItemFooter documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildItemFooterProps

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

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

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

Default
—

ItemGroup

ItemGroupProps

ItemGroup documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildItemGroupProps

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

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

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

Default
—

ItemHeader

ItemHeaderProps

ItemHeader documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildItemHeaderProps

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

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

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

Default
—

ItemMedia

ItemMediaProps

ItemMedia documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildItemMediaProps

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

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

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

Default
—
variant
"default" | "icon" | "image"ItemMediaProps

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

Default
"default"

ItemSeparator

SeparatorProps

ItemSeparator documented props
Prop / typeDescription
class
string | SignalLike<string | undefined>

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

Default
—
decorative
boolean

Configure decorative for ItemSeparator. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
orientation
"horizontal" | "vertical"

Configure orientation for ItemSeparator. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

ItemTitle

ItemTitleProps

ItemTitle documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildItemTitleProps

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

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

Configure class for ItemTitle. 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.

Item Props

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

ItemActions Props

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

ItemContent Props

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

ItemDescription Props

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

ItemFooter Props

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

ItemGroup Props

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

ItemHeader Props

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

ItemMedia Props

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

ItemTitle Props

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

Accessibility

Item is a presentational div by default and can clone a supplied child with asChild. ItemGroup exposes a list role, so its composed children need suitable list-item structure. A visual row is not automatically a button or list item.

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.