# ListItem

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

Category: Data display · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/list-item

ListItem lays out one row of a List. Pass structured props for the common layout, or children for custom content. With asChild, the main area becomes your link or button while actions stay separate, so each row has one clear primary target.

## Import

```tsx
import { List, ListItem } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Structured content

```tsx
import { Badge, Icon, List, ListItem } from '@bindshq/stance-react';

export function Structured() {
  return (
    <List bordered aria-label="Recent deployments">
      <ListItem
        leading={<Icon name="check-circle" size="md" />}
        title="Sales 2026 deployed"
        description="48 mailboxes updated through the Exchange relay"
        meta="09:20"
      />
      <ListItem
        leading={<Icon name="alert-triangle" size="md" />}
        title="2 mailboxes failed"
        description="Mailbox not found for tomas@binds.si"
        meta={
          <Badge tone="danger" size="sm">
            Failed
          </Badge>
        }
      />
    </List>
  );
}
```

### Interactive rows

asChild makes the main area a real link or button. Actions sit outside it.

```tsx
import { Button, Icon, List, ListItem } from '@bindshq/stance-react';

export function Interactive() {
  return (
    <List bordered aria-label="Templates">
      {['Sales 2026', 'Executive'].map((t) => (
        <ListItem
          key={t}
          asChild
          leading={<Icon name="file-text" />}
          title={t}
          description="Assigned to 12 people"
          actions={
            <Button size="sm" variant="ghost">
              Duplicate
            </Button>
          }
        >
          <a href={`#${t}`} />
        </ListItem>
      ))}
    </List>
  );
}
```

### Selected and disabled

```tsx
import { Avatar, List, ListItem } from '@bindshq/stance-react';

export function States() {
  return (
    <List aria-label="Workspaces" dividers={false}>
      <ListItem
        asChild
        selected
        leading={<Avatar name="Binds" shape="square" size="sm" decorative />}
        title="Binds"
      >
        <button type="button" />
      </ListItem>
      <ListItem
        asChild
        leading={<Avatar name="eSignify" shape="square" size="sm" decorative />}
        title="eSignify"
      >
        <button type="button" />
      </ListItem>
      <ListItem
        disabled
        leading={<Avatar name="Archive" shape="square" size="sm" decorative />}
        title="Archive"
        description="Read only"
      />
    </List>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| ListItem | `leading` | `ReactNode` | None | Avatar, icon or thumbnail. |
| ListItem | `title` | `ReactNode` | None | Primary text. |
| ListItem | `description` | `ReactNode` | None | Secondary text. |
| ListItem | `meta` | `ReactNode` | None | Trailing metadata such as a date or badge. |
| ListItem | `actions` | `ReactNode` | None | Trailing actions, outside the interactive area. |
| ListItem | `asChild` | `boolean` | `false` | Render the main area as your single link or button child. |
| ListItem | `selected` | `boolean` | `false` | Highlight and set aria-current. |
| ListItem | `disabled` | `boolean` | `false` | Dim the row and disable pointer interaction. |

## Accessibility

- Renders an <li>, so it must be inside a List (or another <ul>/<ol>).
- With asChild, the whole main area is one link or button whose accessible name combines the title and description.
- Actions render after the main area, so tab order is: row, then its actions.
- selected sets aria-current="true" for navigation-style lists.

## Keyboard

| Keys | Action |
| --- | --- |
| `Tab` | Moves to the row’s link or button, then to its actions. |
| `Enter` | Follows the row link or activates the row button. |

## Guidelines

**Do**

- Give interactive rows a single primary destination.

**Don’t**

- Put buttons inside an asChild link; use actions instead.

## Related

- https://stanceui.com/components/list
- https://stanceui.com/components/avatar
- https://stanceui.com/components/badge