Item

A flexible list row with media, content, and action slots. Three variants, three sizes, and an ItemGroup for stacked lists with separators.

Playground

Upgrade to Pro

Unlock premium features and unlimited projects.

variant

size

media

description

actions

<Item variant="outline">
  <ItemMedia variant="icon">
    <Sparkles />
  </ItemMedia>
  <ItemContent>
    <ItemTitle>Upgrade to Pro</ItemTitle>
    <ItemDescription>
      Unlock premium features and unlimited projects.
    </ItemDescription>
  </ItemContent>
  <ItemActions>
    <Button size="sm">Upgrade</Button>
  </ItemActions>
</Item>

Preview

Compose a row from ItemMedia, ItemContent (holding ItemTitle and ItemDescription) and trailing ItemActions.

Upgrade to Pro

Unlock premium features and unlimited projects.

<Item variant="outline">
  <ItemMedia variant="icon">
    <Sparkles />
  </ItemMedia>
  <ItemContent>
    <ItemTitle>Upgrade to Pro</ItemTitle>
    <ItemDescription>
      Unlock premium features and unlimited projects.
    </ItemDescription>
  </ItemContent>
  <ItemActions>
    <Button size="sm">Upgrade</Button>
  </ItemActions>
</Item>

Installation

npx shadcn@latest add https://espresso-base-ui.vercel.app/r/item.json

Usage

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

<Item variant="outline">
  <ItemMedia variant="icon">
    <Folder />
  </ItemMedia>
  <ItemContent>
    <ItemTitle>Documents</ItemTitle>
    <ItemDescription>128 files</ItemDescription>
  </ItemContent>
  <ItemActions>
    <ChevronRight className="size-4" />
  </ItemActions>
</Item>

Variants

variant sets the surface: default is transparent, outline adds the default shadow border, and muted fills with a soft muted background.

Default

Transparent border, no background.

Outline

Visible border.

Muted

Soft muted background.

<Item variant="default">...</Item>
<Item variant="outline">...</Item>
<Item variant="muted">...</Item>

Sizes

size tunes padding and gaps: default, sm and xs. The xs size drops the description to text-xs and collapses padding inside dropdown menus.

Default size

Roomy padding for list rows.

Small size

Tighter spacing.

Extra small

Compact for menus.

<Item variant="outline" size="default">...</Item>
<Item variant="outline" size="sm">...</Item>
<Item variant="outline" size="xs">...</Item>

Media

ItemMedia takes a variant: icon auto-sizes a leading icon, image crops an image to a rounded square that scales with the item size, and the default variant renders children as-is – an avatar, for instance. When the item has a description, the media nudges down and aligns to the top.

Midnight Reverie

Aria Vale · 3:42

shadcn

m@example.com

Owner

<Item variant="outline">
  <ItemMedia variant="image">
    <img src="/album.jpg" alt="Album art" />
  </ItemMedia>
  <ItemContent>
    <ItemTitle>Midnight Reverie</ItemTitle>
    <ItemDescription>Aria Vale · 3:42</ItemDescription>
  </ItemContent>
  <ItemActions>
    <Button variant="ghost" size="icon-sm">
      <Music />
    </Button>
  </ItemActions>
</Item>

<Item variant="outline">
  <ItemMedia>
    <Avatar>
      <AvatarImage src="https://github.com/shadcn.png" />
      <AvatarFallback>CN</AvatarFallback>
    </Avatar>
  </ItemMedia>
  <ItemContent>
    <ItemTitle>shadcn</ItemTitle>
    <ItemDescription>m@example.com</ItemDescription>
  </ItemContent>
  <ItemActions>
    <Badge variant="secondary">Owner</Badge>
  </ItemActions>
</Item>

Group with separators

Wrap items in ItemGroup for a stacked list – it renders role="list" and tightens its gap when the items use the sm or xs size. Drop an ItemSeparator between rows for a divided list.

Profile

Manage your account info.

Billing

Plans and invoices.

<ItemGroup>
  <Item size="sm">
    <ItemMedia variant="icon">
      <User />
    </ItemMedia>
    <ItemContent>
      <ItemTitle>Profile</ItemTitle>
      <ItemDescription>Manage your account info.</ItemDescription>
    </ItemContent>
    <ItemActions>
      <ChevronRight className="size-4 text-muted-foreground" />
    </ItemActions>
  </Item>
  <ItemSeparator />
  <Item size="sm">
    <ItemMedia variant="icon">
      <CreditCard />
    </ItemMedia>
    <ItemContent>
      <ItemTitle>Billing</ItemTitle>
      <ItemDescription>Plans and invoices.</ItemDescription>
    </ItemContent>
    <ItemActions>
      <ChevronRight className="size-4 text-muted-foreground" />
    </ItemActions>
  </Item>
</ItemGroup>

As a link

Item is built on Base UI's useRender – pass a render element to change the underlying tag. Anchor items get a muted hover background automatically.

Read the documentation

Learn how to compose items with media, content and actions.

<Item variant="outline" render={<a href="#" />}>
  <ItemMedia variant="icon">
    <FileText />
  </ItemMedia>
  <ItemContent>
    <ItemTitle>Read the documentation</ItemTitle>
    <ItemDescription>
      Learn how to compose items with media, content and actions.
    </ItemDescription>
  </ItemContent>
  <ItemActions>
    <ArrowRight className="size-4 text-muted-foreground" />
  </ItemActions>
</Item>

API reference

Item is a compound component. The root carries the variant and size; every other part renders a plain element and accepts className plus its standard element props. ItemHeader and ItemFooter span the full width of the row, so combine them with className="flex-col items-stretch" on the root for card-like layouts.

Item

Prop	Type	Default	Description
variant	"default" \| "outline" \| "muted"	"default"	Surface – transparent (default), bordered with the default shadow (outline), or a soft muted fill (muted).
size	"default" \| "sm" \| "xs"	"default"	Padding and gap scale. xs also shrinks the description to text-xs.
render	ReactElement \| (props, state) => ReactElement	–	Base UI useRender prop – swaps the underlying div for another element, e.g. an anchor or button.

ItemMedia

Prop	Type	Default	Description
variant	"default" \| "icon" \| "image"	"default"	default renders children unchanged; icon auto-sizes an svg to size-4; image crops to a rounded square (size-10, smaller at sm/xs item sizes).

Component	Description
ItemGroup	Vertical stack with role="list" (data-slot="item-group"). Gap tightens when it contains sm or xs items.
ItemSeparator	Horizontal Separator between rows (data-slot="item-separator").
ItemContent	Flexible middle column holding title and description (data-slot="item-content").
ItemTitle	Single-line medium-weight title (data-slot="item-title").
ItemDescription	Muted supporting copy, clamped to two lines; links inside are underlined (data-slot="item-description").
ItemActions	Trailing controls row (data-slot="item-actions").
ItemHeader	Full-width top row with space-between alignment (data-slot="item-header").
ItemFooter	Full-width bottom row with space-between alignment (data-slot="item-footer").

Accessibility & styling hooks

ItemGroup announces as a list via role="list". The root reflects its state as data-slot="item", data-variant and data-size, and the parts expose their own data-slot attributes – the internal styles use these hooks (e.g. media aligning to the top when a description is present), and you can target them from CSS for app-level overrides. The root is focusable-styling ready: it shows a ring on focus-visible when rendered as an interactive element.

Playground

Preview

Installation

Usage

Variants

Sizes

Media

Group with separators

As a link

API reference

Item

ItemMedia

Accessibility & styling hooks

Search documentation