Item

A flexible list row with media, content, and action areas. Supports three variants (default, outline, muted), three sizes (default, sm, xs), and icon or image media. Use ItemGroup to stack multiple items with consistent spacing.

Anatomy

<Item> is the row — accepts variant and size and a render prop to swap the underlying element (e.g. <a> or a router link). ItemMedia holds an icon or image (pass variant="icon" or variant="image"). ItemContent stacks title and description. ItemActions floats controls to the right. ItemHeader and ItemFooter span the full width for metadata rows.

Item Title

Supporting description text.

Variants

default

Default

No border, transparent background.

outline

Outline

Visible border around the row.

muted

Muted

Subtle background fill.

Sizes

default / sm / xs

Default size

Standard padding and text size.

Small size

Reduced padding for dense lists.

Extra-small size

Compact rows for tight spaces.

Examples

Notification list

JD
Jane Doe
2m ago

Commented on your post.

AB
Alex B
15m ago

Mentioned you in a thread.

Navigable list with actions

Packages
12
Team
3
Alerts
5

With image media

Report Q1

PDF · 2.4 MB · Updated yesterday

Report Q2

PDF · 2.4 MB · Updated yesterday

Report Q3

PDF · 2.4 MB · Updated yesterday

Design Guidelines

Do

  • Use ItemGroup for lists. Wrapping Items in ItemGroup applies consistent gap and role="list" semantics automatically.
  • Pick one media variant per list. Mixing icon and image variants in the same list creates misaligned columns — pick one and stick with it throughout the group.
  • Use the render prop for navigation. Pass render=<a href="..." /> or a router link to make the entire row clickable without extra wrapper elements.

Don't

  • Don't put too many actions per item. More than two action buttons per row creates visual noise. Use a DropdownMenu for secondary actions.
  • Don't truncate critical information. ItemTitle is single-line clamped — if the label can be long and important, allow wrapping or show a tooltip.
  • Don't mix sizes within a list. Items in the same ItemGroup should share a size — inconsistent row heights look unpolished.

Developer Reference

Accessibility & Behavior

  • ItemGroup renders with role="list". Individual Item elements are <div>s by default — if they must be list items, pass render=<li />.
  • The render prop on Item uses Base UI's useRender — it merges all props and class names correctly onto the provided element.
  • ItemMedia variant="image" applies a fixed size (size-10) that scales with the item's size prop via data-size selectors.
  • ItemSeparator renders a horizontal Separator with vertical margin — use it inside an ItemGroup to create visual sections.

Usage

import {
  Item,
  ItemMedia,
  ItemContent,
  ItemTitle,
  ItemDescription,
  ItemActions,
  ItemGroup,
  ItemSeparator,
  ItemHeader,
} from "@/components/ui/item"

// Basic item
<Item>
  <ItemMedia variant="icon">
    <Package className="size-4" />
  </ItemMedia>
  <ItemContent>
    <ItemTitle>Packages</ItemTitle>
    <ItemDescription>Manage your packages.</ItemDescription>
  </ItemContent>
  <ItemActions>
    <Button size="sm" variant="ghost">Edit</Button>
  </ItemActions>
</Item>

// As a link
<Item render={<a href="/packages" />}>
  <ItemContent>
    <ItemTitle>Packages</ItemTitle>
  </ItemContent>
</Item>

// Grouped list with separator
<ItemGroup>
  <Item variant="outline">...</Item>
  <ItemSeparator />
  <Item variant="outline">...</Item>
</ItemGroup>

// Variants: "default" | "outline" | "muted"
// Sizes:    "default" | "sm" | "xs"
// Media:    variant="icon" | variant="image"