Item

Visual Hierarchy

Use variant="outline" for prominent list rows, variant="default" for minimal emphasis, and variant="muted" for secondary or read content. Lead with media (icons or avatars) to aid scanning. Place primary actions on the right via ItemActions.

Spacing & Layout

Default size uses p-4 gap-4 for comfortable spacing. Use size="sm" (py-3 px-4 gap-2.5) for dense layouts like notification lists or settings panels. When grouping items, use ItemGroup with ItemSeparator for consistent dividers.

Responsive Behavior

Items flex-wrap by default, so content reflows naturally on narrow screens. On mobile, consider hiding secondary actions behind a dropdown or using size="sm" to conserve vertical space. ItemDescription is capped at 2 lines via line-clamp-2 to prevent overflow.

Color & Contrast

ItemTitle uses text-foreground with font-medium for clear hierarchy. ItemDescription uses text-muted-foreground for secondary emphasis. The outline variant uses border-border which adapts to light and dark modes automatically.

Keyboard Navigation

• Tab -- Move focus to the item or its interactive children
• Enter -- Activate a linked item (when using asChild with an anchor)
• Space -- Activate action buttons within ItemActions
• Escape -- Return focus to the item when an action popover is open

Screen Reader Support

• ItemGroup renders with role="list" by default for semantic grouping
• Add role="listitem" to each Item inside a group for proper list semantics
• Icon-only action buttons require aria-label for screen reader users
• Linked items should use descriptive text or aria-label so the destination is clear

Focus Management

Visible focus ring with 3px width using focus-visible:ring-[3px]. Focus states use focus-visible:border-ring and focus-visible:ring-ring/50 to meet WCAG 2.1 Level AA requirements. When using asChild with links, focus travels naturally through the anchor element.

Touch Targets

Default items have p-4 padding, providing ample touch area. Small items use py-3 px-4, still meeting the 44px minimum height recommendation. Linked items (asChild) make the entire row tappable for easier mobile interaction.

ARIA Attributes

{/* Item group with list semantics */}
<ItemGroup role="list">
  <Item role="listitem">
    <ItemContent>
      <ItemTitle>First item</ItemTitle>
    </ItemContent>
  </Item>
</ItemGroup>

{/* Icon-only actions need aria-label */}
<Item variant="outline">
  <ItemContent>
    <ItemTitle>Notification</ItemTitle>
  </ItemContent>
  <ItemActions>
    <Button size="icon" variant="ghost" aria-label="Dismiss notification">
      <X className="size-4" />
    </Button>
  </ItemActions>
</Item>

{/* Linked item with descriptive accessible name */}
<Item asChild>
  <a href="/settings" aria-label="Open account settings">
    <ItemMedia variant="icon">
      <Settings />
    </ItemMedia>
    <ItemContent>
      <ItemTitle>Settings</ItemTitle>
      <ItemDescription>Manage your account preferences</ItemDescription>
    </ItemContent>
  </a>
</Item>