Item

Anatomy#

Installation#

$ pnpm dlx shadcn@latest add https://www.prfct.dev/r/item.json

Usage#

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

<Item variant="outline">
  <ItemMedia variant="icon">
    <GitBranchIcon />
  </ItemMedia>
  <ItemContent>
    <ItemTitle>Connect a repository</ItemTitle>
    <ItemDescription>Deploy on every push to main.</ItemDescription>
  </ItemContent>
  <ItemActions>
    <Button size="sm" variant="outline">Connect</Button>
  </ItemActions>
</Item>

Examples#

Variants#

default blends into the surface it sits on, outline is a raised tile, and muted is a recessed well.

Sizes#

default, sm and xs scale padding, gaps and media together. Use sm in lists inside cards and xs inside menus.

Media#

ItemMedia holds an icon tile (variant="icon"), an image (variant="image"), or anything else — an Avatar, a file type badge. When the item has a description, media aligns to the top.

List#

ItemGroup turns items into a list: the group gets role="list" and each plain item becomes a list item automatically. ItemSeparator draws hairlines between rows and stays silent for screen readers.

As a link#

When the whole row navigates, render the item as a link with render. Hover and focus styles apply automatically. Wrap a set of links in a <nav> with a label rather than an ItemGroup — a link can't also be a list item.

<Item variant="outline" render={<a href="/docs" />}>
  …
</Item>

Header and footer#

ItemHeader and ItemFooter span the full width above and below the row — for progress, metadata or secondary actions.

Guidelines#

When to use#

• For rows that describe one object with an optional action: a member, a file, an integration, a setting.
• For short lists where each row mixes media, text and controls.

When not to use#

• For many rows compared across the same columns — use a Table.
• For a single, rich object — use a Card.
• For navigation menus with icons only — use a Sidebar or Dropdown Menu.

One primary action per row#

Content#

• Keep titles to one line and descriptions to two — both truncate beyond that.
• Put the most distinguishing information in the title. In a list of people, that's the name; in a list of files, the file name.

Accessibility#

• List semantics are automatic. Inside ItemGroup, plain items are exposed as list items. Rendered elements (links, buttons) keep their own roles.
• Links read as one. A linked item's accessible name is its full text content. Keep titles and descriptions concise so the name stays useful.
• Label icon-only actions. Overflow buttons need a label that names the row: "Manage Maya Chen".
• Decorative media. Icons in ItemMedia are decorative — the title carries the meaning. Informative images need alt text or role="img" with a label.

API reference#

Item#

Built on Base UI's useRender, so it accepts a render prop.

ItemMedia#

ItemGroup#

A <div role="list"> that stacks items and tells them they are list items. Gaps tighten for smaller items.

ItemContent, ItemTitle, ItemDescription#

The text column. Titles clamp to one line and descriptions to two.

ItemActions#

Controls at the end of the row.

ItemHeader, ItemFooter#

Full-width rows above and below the main row.

ItemSeparator#

A horizontal rule between items, hidden from assistive technology inside a group.