bitwarden-browser/libs/components/src/item/item.mdx

import { Meta, Story, Primary, Controls, Canvas } from "@storybook/addon-docs";

import * as stories from "./item.stories";

<Meta of={stories} />

```ts
import { ItemModule } from "@bitwarden/components";
```

# Item

`<bit-item>` is a horizontal card that contains one or more interactive actions.

It is a generic container that can be used for either standalone content, an alternative to tables,
or to list nav links.

<Canvas>
  <Story of={stories.Default} />
</Canvas>

## Primary Content

The primary content of an item is supplied by `bit-item-content`.

### Content Types

The content can be a button, anchor, or static container.

```html
<bit-item>
  <a bit-item-content routerLink="..."> Hi, I am a link. </a>
</bit-item>

<bit-item>
  <button bit-item-content (click)="...">And I am a button.</button>
</bit-item>

<bit-item>
  <bit-item-content> I'm just static :( </bit-item-content>
</bit-item>
```

<Canvas>
  <Story of={stories.ContentTypes} />
</Canvas>

### Content Slots

`bit-item-content` contains the following slots to help position the content:

| Slot               | Description                                         |
| ------------------ | --------------------------------------------------- |
| default            | primary text or arbitrary content; fan favorite     |
| `slot="secondary"` | supporting text; under the default slot             |
| `slot="start"`     | commonly an icon or avatar; before the default slot |
| `slot="end"`       | commonly an icon; after the default slot            |

- Note: There is also an `end` slot within `bit-item` itself. Place
  [interactive secondary actions](#secondary-actions) there, and place non-interactive content (such
  as icons) in `bit-item-content`

```html
<bit-item>
  <button bit-item-content type="button">
    <bit-avatar slot="start" text="Foo"></bit-avatar>
    foo@bitwarden.com
    <ng-container slot="secondary">
      <div>Bitwarden.com</div>
      <div><em>locked</em></div>
    </ng-container>
    <i slot="end" class="bwi bwi-lock" aria-hidden="true"></i>
  </button>
</bit-item>
```

<Canvas>
  <Story of={stories.ContentSlots} />
</Canvas>

## Secondary Actions

Secondary interactive actions can be placed in the item through the `"end"` slot, outside of
`bit-item-content`.

Each action must be wrapped by `<bit-item-action>`.

Actions are commonly icon buttons or badge buttons.

```html
<bit-item>
  <button bit-item-content>...</button>

  <ng-container slot="end">
    <bit-item-action>
      <button type="button" bitBadge variant="primary">Auto-fill</button>
    </bit-item-action>
    <bit-item-action>
      <button type="button" bitIconButton="bwi-clone" aria-label="Copy"></button>
    </bit-item-action>
    <bit-item-action>
      <button type="button" bitIconButton="bwi-ellipsis-v" aria-label="Options"></button>
    </bit-item-action>
  </ng-container>
</bit-item>
```

## Item Groups

Groups of items can be associated by wrapping them in the `<bit-item-group>`.

<Canvas>
  <Story of={stories.MultipleActionList} />
</Canvas>

<Canvas>
  <Story of={stories.SingleActionList} />
</Canvas>

### A11y

Keyboard nav is currently disabled due to a bug when used within a virtual scroll viewport.

Item groups utilize arrow-based keyboard navigation
([further reading here](https://www.w3.org/WAI/ARIA/apg/patterns/grid/examples/layout-grids/#kbd_label)).

Use `aria-label` or `aria-labelledby` to give groups an accessible name.

```html
<bit-item-group aria-label="My Items">
  <bit-item>...</bit-item>
  <bit-item>...</bit-item>
  <bit-item>...</bit-item>
</bit-item-group>
```

### Virtual Scrolling

<Canvas>
  <Story of={stories.VirtualScrolling} />
</Canvas>