# Item

A flexible row for grouping media, content, and actions.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<ComponentPreview name="item" title="item.tsx" align="start" previewClassName="h-auto">
<Component />
</ComponentPreview>

Item is a flexible row primitive for grouping media, content, and actions. Use it for settings lists, activity feeds, user rows, or any horizontal layout with a leading visual and trailing controls.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add item
```
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>

```bash
npm install class-variance-authority
```

<Step>
Optional — install <code>avatar</code> to replicate the full demo:
</Step>

```bash
npx frakment add avatar
```

<div className="text-sm text-muted-foreground">

The demo uses `<Avatar>` with the 5 AVIF avatars included in the avatar component. Skip this step if you only need the `Item` primitive.

</div>

<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="item" title="components/ui/item.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx title="item.tsx"
import { Item, ItemContent, ItemMedia, ItemTitle } from "@/components/ui/item";

<DocsBaseSwitcher base="web" component="item" className="mb-6" />
```

```tsx title="item.tsx"
<Item>
  <ItemMedia>JS</ItemMedia>
  <ItemContent>
    <ItemTitle>Jane Smith</ItemTitle>
  </ItemContent>
</Item>
```

## Composition [#composition]

```text
Item
├── ItemMedia
├── ItemContent
│   ├── ItemTitle
│   └── ItemDescription
└── ItemActions
```

## Variants [#variants]

Three styles: `default` (bordered card), `outline` (transparent with border), `muted` (soft background, no border).

<ComponentPreview name="item" title="item.tsx" align="start" previewClassName="h-auto">
<div className="flex w-full max-w-md flex-col gap-3 p-4">
  <div className="flex flex-col gap-1">
    <span className="text-xs font-medium text-muted-foreground">default</span>
    
<Component>
<Component>
<Component>
Default row
</Component>
</Component>
</Component>

  </div>
  <div className="flex flex-col gap-1">
    <span className="text-xs font-medium text-muted-foreground">outline</span>
    
<Component variant="outline">
<Component>
<Component>
Outline row
</Component>
</Component>
</Component>

  </div>
  <div className="flex flex-col gap-1">
    <span className="text-xs font-medium text-muted-foreground">muted</span>
    
<Component variant="muted">
<Component>
<Component>
Muted row
</Component>
</Component>
</Component>

  </div>
</div>
</ComponentPreview>

## With media [#with-media]

Put an icon, avatar, or badge in `ItemMedia`. Icons without a `size-*` class are auto-sized to 16px.

<ComponentPreview name="item" title="item.tsx" align="start" previewClassName="h-auto">
<div className="w-full max-w-sm p-4">
  
<Component>
<Component>
<Component>
<span className="flex size-8 items-center justify-center rounded-full bg-muted text-xs font-medium">
    A
  </span>
</Component>

  
<Component>
<Component>
Aria Chen
</Component>
</Component>
</Component>

  
<Component>
<Component>
<span className="flex size-8 items-center justify-center rounded-full bg-muted text-xs font-medium">
    B
  </span>
</Component>

  
<Component>
<Component>
Ben Ortiz
</Component>
</Component>
</Component>

  
<Component>
<Component>
<span className="flex size-8 items-center justify-center rounded-full bg-muted text-xs font-medium">
    C
  </span>
</Component>

  
<Component>
<Component>
Cleo Park
</Component>
</Component>
</Component>
</Component>

</div>
</ComponentPreview>

## With description [#with-description]

Add `ItemDescription` below `ItemTitle` for a secondary line.

<ComponentPreview name="item" title="item.tsx" align="start" previewClassName="h-auto">
<div className="w-full max-w-sm p-4">
  
<Component>
<Component>
<Component>
<Component>
Deployed v1.2.3
</Component>

  
<Component>
2 minutes ago
</Component>
</Component>
</Component>

  
<Component>
<Component>
<Component>
Ran migrations
</Component>

  
<Component>
14 minutes ago
</Component>
</Component>
</Component>

  
<Component>
<Component>
<Component>
Merged PR #42
</Component>

  
<Component>
1 hour ago
</Component>
</Component>
</Component>
</Component>

</div>
</ComponentPreview>

## With actions [#with-actions]

Add `ItemActions` as the last child for a trailing button, badge, or amount.

<ComponentPreview name="item" title="item.tsx" align="start" previewClassName="h-auto">
<div className="w-full max-w-sm p-4">
  
<Component>
<Component variant="muted">
<Component>
<Component>
Pro plan
</Component>

  
<Component>
Billed monthly
</Component>
</Component>

  
<Component>
<span className="text-sm font-medium tabular-nums">$20/mo</span>
</Component>
</Component>

  
<Component variant="muted">
<Component>
<Component>
Team plan
</Component>

  
<Component>
Billed annually
</Component>
</Component>

  
<Component>
<span className="text-sm font-medium tabular-nums">$200/yr</span>
</Component>
</Component>
</Component>

</div>
</ComponentPreview>

## In context [#in-context]

Combine with [Spinner](/docs/components/web/spinner) for a live processing row.

<ComponentPreview name="item" title="item.tsx" align="start" previewClassName="h-auto">
<div className="w-full max-w-sm p-4">
  
<Component variant="muted">
<Component>
<Component />
</Component>

  
<Component>
<Component>
Processing payment...
</Component>
</Component>

  
<Component>
<span className="text-sm tabular-nums">$100.00</span>
</Component>
</Component>

</div>
</ComponentPreview>

## In Context [#in-context-1]

### Settings row [#settings-row]

<ComponentPreview name="item-settings" title="item-settings.tsx" src="examples/item-settings.tsx">
<ItemSettings />
</ComponentPreview>

## API Reference [#api-reference]

### Item [#item]

<PropsTable rows={[{"name":"variant","type":"default | outline | muted","default":"default","description":"Visual style of the row."}]} />

### ItemMedia / ItemContent / ItemTitle / ItemDescription / ItemActions [#itemmedia--itemcontent--itemtitle--itemdescription--itemactions]

Extend `React.ComponentProps<"div">`. Each maps to a `data-slot` attribute for CSS targeting.

## As prop [#as-prop]

`Item` also accepts an `as` prop to render a custom element such as `<a>` or `<li>`.

## Data Attributes [#data-attributes]

| Attribute | Values |
| :-- | :-- |
| `data-slot` | `item`, `item-group`, `item-media`, `item-content`, `item-title`, `item-description`, `item-actions` |
| `data-variant` | `default` \| `outline` \| `muted` |
| `data-size` | `default` \| `sm` |

## Accessibility [#accessibility]

- `Item` renders a `<div>` — for interactive rows, use `as` with `<a>` or `<button>` so keyboard and screen readers work.
- `ItemMedia` should be `aria-hidden` when the visual is decorative (e.g., a status dot).
- `ItemTitle` acts as the accessible name — write it as a short label.

## Best Practices [#best-practices]

- **Use for list rows with mixed content.** Media + content + actions fits in one Item.
- **Keep the media square.** A 32px to 40px square reads as an avatar or icon.
- **Actions belong in `ItemActions`.** Do not float buttons inside content.
- **One action cluster.** More than three actions belong in a dropdown.
## Related Components [#related-components]

- [Card](/docs/components/web/card) — elevated container
- [Marker](/docs/components/web/marker) — inline status row
- [Attachment](/docs/components/web/attachment) — file row