# Item

> A list row with media, a title, a description and actions.

An item is a row in a list: a picture or icon, a title, one line of description and an action, such as an artist in a list or a setting in a menu.

## When to use

- Use it for lists on phones and in panels: artists, releases, account menus, settings.
- Use a [Table](https://design.sosialoka.tech/components/table/) for records with many columns that people compare.
- Make the whole row a link when it opens a page; keep a separate button when the row has its own action.
- Item is the row of the [Mobile app](https://design.sosialoka.tech/patterns/mobile-app/) pattern.

_Live preview of the React and Vue versions: https://design.sosialoka.tech/components/item/_

## Anatomy

1. Leading avatar or icon
2. Title and meta
3. Trailing chevron
4. Divider

A row on `radius-lg` with `p-3` and a 12px gap: media on the left (an Avatar or a 40px icon), the title (`text-sm font-medium`) and description (`text-sm text-muted-foreground`), then actions on the right. As a link, it turns `accent` on hover.

## Variants

| Variant | Use it for |
| --- | --- |
| `default` | Rows in a menu or a list with separators. |
| `outline` | Rows that stand on their own, such as cards in a list. |
| `muted` | A row that needs a quiet surface, such as a summary. |

## Props

| React | Vue | Flutter | Type | Default | Use |
| --- | --- | --- | --- | --- | --- |
| `variant` | `variant` | `ShadItem` / `.outline` / `.muted` | text | `default` | The look. |
| `size` | `size` | `size` | `default`, `sm`, `xs` (React only) | `default` | The padding. |
| `render={<a href />}` | `as-child` with a link | `onPressed` | element | `div` | Makes the whole row a link. |
| `ItemMedia`, `ItemTitle`, `ItemDescription`, `ItemActions` | same | `media`, `title`, `description`, `actions` | element | none | The parts of the row. |

## Code

**React**
```tsx
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { Button } from "@/components/ui/button"
import { Item, ItemActions, ItemContent, ItemDescription, ItemGroup, ItemMedia, ItemTitle } from "@/components/ui/item"

const artists = [
  { name: "Rara Senandika", initials: "RS", detail: "3 rilis · Pop" },
  { name: "Bima Laras", initials: "BL", detail: "5 rilis · Folk" },
  { name: "Nada Kirana", initials: "NK", detail: "2 rilis · R&B" },
]

export default function ItemDemo() {
  return (
    <ItemGroup className="w-full max-w-md gap-2">
      {artists.map((artist) => (
        <Item key={artist.name} variant="outline">
          <ItemMedia>
            <Avatar>
              <AvatarFallback>{artist.initials}</AvatarFallback>
            </Avatar>
          </ItemMedia>
          <ItemContent>
            <ItemTitle>{artist.name}</ItemTitle>
            <ItemDescription>{artist.detail}</ItemDescription>
          </ItemContent>
          <ItemActions>
            <Button variant="outline" size="sm" aria-label={`Lihat ${artist.name}`}>
              Lihat
            </Button>
          </ItemActions>
        </Item>
      ))}
    </ItemGroup>
  )
}
```

**Vue**
```vue
<script setup lang="ts">
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { Button } from "@/components/ui/button"
import { Item, ItemActions, ItemContent, ItemDescription, ItemGroup, ItemMedia, ItemTitle } from "@/components/ui/item"

const artists = [
  { name: "Rara Senandika", initials: "RS", detail: "3 rilis · Pop" },
  { name: "Bima Laras", initials: "BL", detail: "5 rilis · Folk" },
  { name: "Nada Kirana", initials: "NK", detail: "2 rilis · R&B" },
]
</script>

<template>
  <ItemGroup class="w-full max-w-md gap-2">
    <Item v-for="artist in artists" :key="artist.name" variant="outline">
      <ItemMedia>
        <Avatar>
          <AvatarFallback>{{ artist.initials }}</AvatarFallback>
        </Avatar>
      </ItemMedia>
      <ItemContent>
        <ItemTitle>{{ artist.name }}</ItemTitle>
        <ItemDescription>{{ artist.detail }}</ItemDescription>
      </ItemContent>
      <ItemActions>
        <Button variant="outline" size="sm" :aria-label="`Lihat ${artist.name}`">Lihat</Button>
      </ItemActions>
    </Item>
  </ItemGroup>
</template>
```

**Flutter**
```dart
import 'package:flutter/widgets.dart';
import 'package:shadcn_ui/shadcn_ui.dart';

const itemArtists = [('Rara Senandika', 'RS', '3 rilis · Pop'), ('Bima Laras', 'BL', '5 rilis · Folk'), ('Nada Kirana', 'NK', '2 rilis · R&B')];

class ItemDemo extends StatelessWidget {
  const ItemDemo({super.key});

  @override
  Widget build(BuildContext context) {
    return ConstrainedBox(
      constraints: const BoxConstraints(maxWidth: 448),
      child: Column(
        mainAxisSize: MainAxisSize.min,
        spacing: 8,
        children: [
          for (final (name, initials, detail) in itemArtists)
            ShadItem.outline(
              media: ShadAvatar(null, placeholder: Text(initials)),
              title: Text(name),
              description: Text(detail),
              actions: Semantics(
                label: 'Lihat $name',
                button: true,
                child: ExcludeSemantics(child: ShadButton.outline(size: ShadButtonSize.sm, onPressed: () {}, child: const Text('Lihat'))),
              ),
            ),
        ],
      ),
    );
  }
}
```

## Install

**React**
```bash
npx shadcn@latest add https://design.sosialoka.tech/r/react/item.json
```

**Vue**
```bash
npx shadcn-vue@latest add https://design.sosialoka.tech/r/vue/item.json
```

## Accessibility

- Name each action with what it acts on: "Lihat Rara Senandika", not only "Lihat".
- When the whole row is a link, don't nest another button inside it.
- Put items in a list (`ItemGroup`) so screen readers announce how many there are.
