# Sequencer

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

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

```ts
import { Sequencer } from "@audio-ui/react/sequencer";
```

| Export | Kind | What it is |
| --- | --- | --- |
| `Sequencer.Cell` | function | One step of a row: a toggle button, pressed when the step is on. |
| `Sequencer.Root` | function | A grid of steps to switch on and off, one row per sound: the pattern of a drum machine. |
| `Sequencer.Cells` | function | Renders `children` once per step of the row it is in: the place to put a `Sequencer.Cell`. |
| `Sequencer.Row` | function | One sound's row of steps. |
| `Sequencer.Rows` | function | Renders `children` once per row: the place to put a `Sequencer.Row`. |
| `Sequencer.Velocity` | function | How loud one step plays, as a bar from the bottom of its box: the height is the velocity, through the `--sequencer-velocity` CSS variable. |

## Anatomy

Import the registry component for the ready-made look, or compose the primitive's parts yourself.

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

<Sequencer.Root>
  <Sequencer.Rows>
    {(row) => (
      <Sequencer.Row index={row}>
        <Sequencer.Cells>
          {(step) => <Sequencer.Cell step={step} />}
        </Sequencer.Cells>
      </Sequencer.Row>
    )}
  </Sequencer.Rows>
</Sequencer.Root>;
```

## API reference

### Root

A grid of steps to switch on and off, one row per sound: the pattern of a drum machine. Pressing a cell flips it, and dragging on carries the new state across every cell the pointer crosses. The cells are one tab stop, and the arrow keys move between them. The step being played comes from `source` and is marked on its cells straight in the DOM with `data-current`, so a clock ticking every step never re-renders React. Renders a `<div>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `Pattern` |  | Uncontrolled starting pattern: a row per sound, each a list of steps. |
| `defaultVelocities` | `Velocities` |  | Uncontrolled starting velocities. |
| `disabled` | `boolean` |  |  |
| `onValueChange` | `(value: boolean[][], eventDetails: ChangeEventDetails) => void` |  | Fires while cells are flipped. `eventDetails.cancel()` keeps the pattern as it was. |
| `onValueCommitted` | `(value: boolean[][], eventDetails: CommitEventDetails) => void` |  | Fires when a press, a paint or a key press that changed the pattern ends. |
| `onVelocityChange` | `(velocities: number[][], eventDetails: VelocityChangeEventDetails) => void` |  | Fires while a velocity is drawn or nudged. `eventDetails.cancel()` keeps the velocities as they were. |
| `onVelocityCommitted` | `(velocities: number[][], eventDetails: VelocityCommitEventDetails) => void` |  | Fires when a drag, a key press or a reset that changed a velocity ends. |
| `source` | `Source<number>` |  | The step being played, a live value followed without re-rendering; its cells get `data-current`. |
| `value` | `Pattern` |  | The pattern: a row per sound, each a list of steps. |
| `velocities` | `Velocities` |  | How loud each step plays, 0…1, a row per sound like the pattern; a step it does not list plays at full. |

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-disabled` | Present when disabled. |
| `data-painting` | Whether a pointer is painting cells. |

### Rows

Renders `children` once per row: the place to put a `Sequencer.Row`. Renders no element of its own.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `(row: number) => React.ReactNode` |  |  |

### Cells

Renders `children` once per step of the row it is in: the place to put a `Sequencer.Cell`. Renders no element of its own.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `(step: number) => React.ReactNode` |  |  |

### Row

One sound's row of steps. Name it with `aria-label`, such as "Kick". Renders a `<div>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `index` | `number` |  | Which row this is, from the top. |

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-disabled` | Present when disabled. |
| `data-painting` | Whether a pointer is painting cells. |

### Cell

One step of a row: a toggle button, pressed when the step is on. Press it and drag on to paint the same state across the cells you cross; focused, Space or Enter flips it and the arrow keys move to the next cell. Name it with `aria-label`, such as "Kick, step 5". The step being played gets `data-current`. Renders a `<button>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `step` | `number` |  | Which step this is, from the left. |

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-disabled` | Present when disabled. |
| `data-on` | Whether the step is on: also `aria-pressed`. |
| `data-painting` | Present when painting. |

### Velocity

How loud one step plays, as a bar from the bottom of its box: the height is the velocity, through the `--sequencer-velocity` CSS variable. Pressing it sets the velocity where the pointer is, and dragging on draws across the steps of the row. Alt + click or Delete brings it back to full. A native `<input type="range">` inside takes the arrow keys and carries the accessible name. Put one per step of a `Sequencer.Row`, in a row of its own under the cells. Renders a `<div>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `step` | `number` |  | Which step this is, from the left. |
| `getAriaValueText` | `(velocity: number) => string` |  | Returns how a velocity, 0…1, is announced. Defaults to a percentage. |

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-disabled` | Present when disabled. |
| `data-on` | Whether the step is on. |

## Styled

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