# Pad

> The headless Pad of @audio-ui/react: its parts, what each renders and owns, and their props.

```bash
npm install @audio-ui/react
```

```ts
import { Pad } from "@audio-ui/react/pad";
```

| Export | Kind | What it is |
| --- | --- | --- |
| `Pad.Item` | function | One pad. |
| `Pad.Root` | function | A grid of pads to strike: each one sounds while held, by pointer or from the keyboard, and each pointer holds its own pad, so several can be played at once on a touch screen. |

## Anatomy

Import the primitive and assemble its parts.

```tsx
import { Pad } from "@audio-ui/react";

<Pad.Root>
  <Pad.Item value="kick">Kick</Pad.Item>
</Pad.Root>
```

## API reference

### Root

A grid of pads to strike: each one sounds while held, by pointer or from the keyboard, and each pointer holds its own pad, so several can be played at once on a touch screen. A strike is harder where a pen or screen presses harder, or else toward the top of the pad. The pads are one tab stop: the left and right arrows walk them in reading order, the up and down arrows by a row of `columns`. Renders a `<div>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `activePads` | `readonly string[]` |  | Pads lit from elsewhere, such as a sequencer or a MIDI input, on top of the ones held here. |
| `columns` | `number` | `4` | How many pads a row holds: what the up and down arrows move by. Lay the grid out to match. |
| `disabled` | `boolean` |  |  |
| `onPadOff` | `(value: string, eventDetails: OffEventDetails) => void` |  | Fires when a pad is released, loses focus while held, or is choked by another pad of its group (`reason: "choke"`). |
| `onPadOn` | `(value: string, eventDetails: OnEventDetails) => void` |  | Fires when a pad is struck, with `eventDetails.velocity` from 0 to 1. `eventDetails.cancel()` keeps it silent. |

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-disabled` | Present when disabled. |

### Item

One pad. It sounds while held: by pointer, or with Enter or Space while focused. Its accessible name comes from its content, or `aria-label`. How hard it was last struck is the `--pad-velocity` CSS variable, from 0 to 1. Renders a `<button>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `chokeGroup` | `string` |  | Pads sharing a choke group stop each other: striking one stops the last one struck, held or still ringing. |
| `disabled` | `boolean` |  |  |
| `value` | `string` |  | What identifies this pad in `onPadOn`, `onPadOff` and `activePads`. |

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-active` | Whether the pad is sounding: held here, or listed in `activePads`. |
| `data-disabled` | Present when disabled. |

## Styled

The registry's styled Pad, its usage and interaction: [Pad](/docs/components/base/pad).