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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthInstallation
Import Item and subcomponents (ItemMedia, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemGroup, …) from @/components/kamod-ui/item.
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
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 { 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.
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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthVariants
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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthSizes
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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthIcon 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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthAvatar 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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthImage 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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthGroup
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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthLink (asChild)
Make the Destination the Real Interactive Element. Set asChild on Item with an anchor when the entire row should navigate. The link receives the row's hover and focus treatment, creating one coherent target instead of a decorative container around a small text link.
Use a meaningful href, keep the link's label clear and avoid nesting other interactive controls inside it; separate actions belong in a non-link item composition.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthSeparator
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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthInside 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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthProps 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.
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.Item
ItemProps
| Prop / type | Description |
|---|---|
asChild | Configure
|
children | Configure
|
class | Configure
|
size | Configure
|
variant | Configure
|
ItemActions
ItemActionsProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
ItemContent
ItemContentProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
ItemDescription
ItemDescriptionProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
ItemGroup
ItemGroupProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
ItemHeader
ItemHeaderProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
ItemMedia
ItemMediaProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
variant | Configure
|
ItemSeparator
SeparatorProps
| Prop / type | Description |
|---|---|
class | Configure
|
decorative | Configure
|
orientation | Configure
|
ItemTitle
ItemTitleProps
| 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.
Item Props
2 declared fieldsItemPropsItem.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 fieldItemActionsPropsItemActions.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 fieldItemContentPropsItemContent.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 fieldItemDescriptionPropsItemDescription.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 fieldItemFooterPropsItemFooter.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 fieldItemGroupPropsItemGroup.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 fieldItemHeaderPropsItemHeader.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 fieldItemMediaPropsItemMedia.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 fieldItemTitlePropsItemTitle.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.
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.