# List

> A semantic list of related items with dividers, density and an optional bordered surface.

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

Use List for collections people scan top to bottom, such as members, templates or recent activity. Each row is a ListItem. Use Table instead when people need to compare values across columns.

## 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

### Basic

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

export function Basic() {
  return (
    <List aria-label="Organisation members">
      {[
        ['Amara Okafor', 'Sales · amara@binds.si', 'Owner'],
        ['Lukas Novak', 'Engineering · lukas@binds.si', 'Admin'],
        ['Priya Raman', 'Legal · priya@binds.si', 'Member'],
      ].map(([name, description, role]) => (
        <ListItem
          key={name}
          leading={<Avatar name={name!} size="sm" decorative />}
          title={name}
          description={description}
          meta={<Badge size="sm">{role}</Badge>}
        />
      ))}
    </List>
  );
}
```

### Bordered with actions

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

export function Bordered() {
  return (
    <List bordered aria-label="Signature templates">
      {['Sales 2026', 'Executive', 'Support'].map((t) => (
        <ListItem
          key={t}
          leading={<Icon name="pen-nib" />}
          title={t}
          description="Updated 2 days ago"
          actions={
            <Button size="sm" variant="ghost">
              Edit
            </Button>
          }
        />
      ))}
    </List>
  );
}
```

### Ordered steps

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

export function Ordered() {
  return (
    <List ordered dividers={false} density="sm" aria-label="Deployment steps">
      <ListItem
        leading={
          <Badge variant="solid" tone="inverse" size="sm">
            1
          </Badge>
        }
        title="Connect your Exchange relay"
      />
      <ListItem
        leading={
          <Badge variant="solid" tone="inverse" size="sm">
            2
          </Badge>
        }
        title="Assign templates to departments"
      />
      <ListItem
        leading={
          <Badge variant="solid" tone="inverse" size="sm">
            3
          </Badge>
        }
        title="Deploy and verify signatures"
      />
    </List>
  );
}
```

### Density

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

export function Density() {
  return (
    <div
      style={{
        display: 'grid',
        gap: 24,
        gridTemplateColumns: 'repeat(auto-fit, minmax(220px, 1fr))',
      }}
    >
      {(['sm', 'lg'] as const).map((d) => (
        <List key={d} density={d} bordered aria-label={`Density ${d}`}>
          <ListItem title="Billing contact" description="finance@binds.si" />
          <ListItem title="Security contact" description="security@binds.si" />
        </List>
      ))}
    </div>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| List | `ordered` | `boolean` | `false` | Render <ol> instead of <ul>. |
| List | `dividers` | `boolean` | `true` | Lines between items. |
| List | `density` | `'sm' \| 'md' \| 'lg'` | `'md'` | Vertical padding of items. |
| List | `bordered` | `boolean` | `false` | Wrap the list in a bordered surface. |
| List | `...props` | `HTMLAttributes<HTMLUListElement>` | None | Native list attributes; use aria-label to name the list. |

## Accessibility

- Renders native <ul> or <ol>, so screen readers announce the number of items.
- Name lists that stand alone with aria-label or aria-labelledby.
- Keep interactive items to one primary target per row (see ListItem asChild) so tab order stays predictable.

## Guidelines

**Do**

- Keep titles short and put secondary detail in the description.
- Use ordered lists when sequence matters.

**Don’t**

- Nest interactive elements inside an interactive row.
- Use List for tabular comparisons.

## Related

- https://stanceui.com/components/list-item
- https://stanceui.com/components/searchable-list
- https://stanceui.com/components/virtualized-list
- https://stanceui.com/components/table