Item

InstallCopy Anchor Link

pnpm exec vegastack-design verify item

pnpm dlx shadcn@4.21.0 add @vegastack/item

UsageCopy Anchor Link

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

<Item>
  <ItemMedia variant="icon">
    <InboxIcon />
  </ItemMedia>
  <ItemContent>
    <ItemTitle>Title</ItemTitle>
    <ItemDescription>Description</ItemDescription>
  </ItemContent>
  <ItemActions>
    <Button>Action</Button>
  </ItemActions>
</Item>;

AnatomyCopy Anchor Link

ExamplesCopy Anchor Link

CompositionCopy Anchor Link

ItemMedia, ItemContent and ItemActions share one flex row; ItemHeader and ItemFooter take a full basis, so they sit above and below that row inside the same item.

Item vs FieldCopy Anchor Link

Use Field when you need to display a form input such as a checkbox, input, radio or select — it owns the label association, the description and the error. Use Item when you only need to display content: a title, a description and actions.

VariantCopy Anchor Link

Use the variant prop to change the visual style of the item: default, outline or muted.

SizeCopy Anchor Link

Use the size prop to change the size of the item. Available sizes are default, sm and xs. An enclosing ItemGroup tightens its own gap to match. The tier steps the padding and the gaps; of the parts inside, only ItemMedia shrinks — the title and description keep their type size (xs alone drops the description to text-xs).

IconCopy Anchor Link

Use ItemMedia with variant="icon" to display an icon.

AvatarCopy Anchor Link

Use the default ItemMedia to display an avatar, or a stack of them.

ImageCopy Anchor Link

Use ItemMedia with variant="image" to display an image — a fixed square that clips its corners and tracks the item's size.

PreviewCode

Midnight City Lights — Electric Nights

Neon Dreams

3:45

Coffee Shop Conversations — Urban Stories

The Morning Brew

4:05

Digital Rain — Binary Beats

Cyber Symphony

3:30

GroupCopy Anchor Link

Use ItemGroup to group related items, and ItemSeparator to rule between them. The group renders role="list", so each item carries role="listitem" and the rule between two rows is hidden from assistive technology.

variant="flush" is the group for rows inside a card: no gap between rows, and the rows bleed into the card's padding so their text lines up with the card's own content.

<Card>
  <CardContent>
    <ItemGroup variant="flush">…</ItemGroup>
  </CardContent>
</Card>

HeaderCopy Anchor Link

Use ItemHeader to add a header above the item content — a cover image, for instance.

PreviewCode

vs-1.5-sm

Everyday tasks and UI generation.

vs-1.5-lg

Advanced thinking or reasoning.

vs-2.0-mini

Open source model for everyone.

LinkCopy Anchor Link

Use the render prop to render the item as a link. The hover state applies to the anchor, and the focus outline is the global one — the item's own recipe carries no ring.

DropdownCopy Anchor Link

At size="xs" an item drops its padding inside a dropdown menu, so it composes as a rich menu row.

RTLCopy Anchor Link

Every gap and padding is written in logical properties, so a right-to-left document mirrors the media, content and actions columns without any extra work.

ChecklistCopy Anchor Link

A getting-started checklist is a composition, not a component: a Progress over an ItemGroup of Item size="sm" rows, each led by a StatusIcon that names its state. The host owns which steps are done.

Link rows in a groupCopy Anchor Link

An Item rendered as a link or a button inside an ItemGroup keeps its own role: the listitem the group requires moves to a <div role="listitem" data-slot="item-listitem"> wrapper around it. A RelativeTime or truncated cell inside such a row is not a tab stop of its own — the row is the one control.

Grouped with labelsCopy Anchor Link

ItemGroupLabel is a small heading (an h3 by default; pass render={<h2 />} for another level) that names the ItemGroup rendered immediately after it, so each group is announced as a named list. The name is linked after mount; to name the list in server-rendered HTML as well, give the label an id and the group aria-labelledby yourself.

HighlightedCopy Anchor Link

highlighted flashes a row the user just created or changed: the accent wash eases in and the row is marked data-highlighted. Clear the flag after a moment to return it to rest — never hand-write data-highlighted:bg-accent. (DataList rows take the same state through highlightedIds or rowProps.)

<Item highlighted={justChanged.has(task.id)}>…</Item>

API ReferenceCopy Anchor Link

AccessibilityCopy Anchor Link

• Item is a div by default and carries no role of its own — it is content, not a control. Pass render to make it an anchor or a button when the whole row is activatable.
• ItemGroup renders role="list", which admits only listitem children. Every Item inside it takes role="listitem" through context; a row rendered as a link or a button keeps its own role and gets a listitem wrapper instead. ItemSeparator is hidden with aria-hidden — the list already conveys the separation, and an exposed role="separator" there is a critical aria-required-children failure.
• ItemGroupLabel names the group after it through aria-labelledby, so the list is announced with its heading.
• A row that owns an accessible description (a command option, a menu item) provides ItemDescriptionContext; an ItemDescription inside it registers its id, and the row points aria-describedby at it, so the second line is read as a description rather than as part of the name.
• On :focus-visible the global 2px outline in base.css applies (FOC-1). The item's recipe carries no focus ring, no ring-3 glow and no outline-none of its own (FOC-6).
• ItemTitle never clamps on the element that is also a flex container; wrap the text in an inner span when it has to truncate (LAY-11).
• An icon-only action inside ItemActions has no visible text — give it an aria-label.

Do / Don'tCopy Anchor Link

DeviationsCopy Anchor Link

Upstream's file plus packages/ui/upstream/patches/item.patch. Every hunk:

• API-29 — Item takes highlighted: data-highlighted and the bg-accent wash eased in over duration-slow, the "just changed" flash.
• A11Y-7 — ItemGroup licenses role="listitem" on the items inside it, through context, and hides the separator's rule from assistive tech. role="list" admits only listitem children, so upstream's own composition is a critical aria-required-children violation as shipped. A row rendered as a link or a button keeps its own role and the listitem moves to a wrapper, and its truncated cells are not tab stops of their own.
• API-16 — "use client" is added: useRender calls React.useRef internally, so the module throws on import in a React Server Component without the boundary.
• API-19 — ItemDescriptionContext and useItemDescriptionId() let a row link its ItemDescription as its accessible description. Outside such a row the description renders as upstream's.
• API-20 — ItemGroupLabel, a heading part that names the ItemGroup after it.
• DOC-2 — cn is imported from @vegastack/design, and the file carries the registry provenance header.
• FOC-1, FOC-6 — itemVariants loses upstream's outline-none, focus-visible:border-ring and 3px focus-visible:ring-ring/50 glow, so the global 2px outline is what a focused item shows.
• LAY-11 — ItemTitle loses line-clamp-1, which upstream sets on the same element as flex. Truncation goes on an inner span instead.
• API-37 — ItemGroup takes variant (default · flush): flush lays rows with no gap and bleeds them into the enclosing card's padding. MK, 2026-10-26.