# Envelope

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

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

```ts
import { Envelope } from "@audio-ui/react/envelope";
```

| Export | Kind | What it is |
| --- | --- | --- |
| `Envelope.Breakpoint` | type | A point of the ramp, and how the segment leaving it bends: `curve` from -1 to 1, 0 or unset for a straight line. |
| `Envelope.Fill` | function | The area under the curve. |
| `Envelope.Graph` | function | The drawing surface, a 100×100 stretched viewBox: holds `Line` and `Fill`, and a double click on it adds a point. |
| `Envelope.Line` | function | The envelope curve through the points. |
| `Envelope.Point` | function | A draggable handle for the point at `index`, positioned with `left`/`bottom` percentages over the `Graph`. |
| `Envelope.Points` | function | Renders one child per point, in `x` order. |
| `Envelope.Root` | function | Groups all parts of the breakpoint envelope and owns its points, each normalized to 0…1 on both axes and kept sorted by `x`. |
| `Envelope.Segment` | function | A handle on the middle of the segment leaving the point at `index`: drag it up or down to bend the segment, so it follows the pointer on the curve's midpoint. |
| `Envelope.Segments` | function | Renders one child per segment between two points, in `x` order. |

## Anatomy

Import the primitive and assemble its parts.

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

<Envelope.Root>
  <Envelope.Graph>
    <Envelope.Fill />
    <Envelope.Line />
  </Envelope.Graph>
  <Envelope.Segments>
    <Envelope.Segment />
  </Envelope.Segments>
  <Envelope.Points>
    <Envelope.Point />
  </Envelope.Points>
</Envelope.Root>
```

## API reference

### Root

Groups all parts of the breakpoint envelope and owns its points, each normalized to 0…1 on both axes and kept sorted by `x`. Points are dragged and nudged with the keyboard; a double click on the `Graph` adds one and a double click (or Delete) on a `Point` removes it, within `minPoints` / `maxPoints`. Renders a `<div>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `GeomPoint[]` |  | Uncontrolled starting points. Defaults to an ADSR-like shape. |
| `disabled` | `boolean` |  |  |
| `format` | `Intl.NumberFormatOptions` |  | Formats point coordinates for each point's `aria-valuetext`. |
| `locale` | `Intl.LocalesArgument` |  |  |
| `maxPoints` | `number` |  | Ceiling on the number of points; adding is blocked at this count. Equal to `minPoints`, the shape is fixed. |
| `minPoints` | `number` | `2` | Floor on the number of points; removal is blocked at this count. |
| `onValueChange` | `(value: GeomPoint[], eventDetails: ChangeEventDetails) => void` |  | Fires on every change: drag, keyboard, add and remove. |
| `onValueCommitted` | `(value: GeomPoint[], eventDetails: CommitEventDetails) => void` |  | Fires when an interaction that changed the points ends. |
| `step` | `number` | `0.01` | Keyboard step on both axes, in normalized units. |
| `snap` | `number \| { x: number; y: number }` | `0` | Grid the pointer snaps points to, in normalized units: 0.25 snaps to quarters, 0 is no grid, and `{ x, y }` sets a step for each axis (`{ x: 0.125, y: 0 }` snaps across and leaves the level free). Holding Cmd/Ctrl leaves the grid, and Shift's fine drag ignores it. Keys move by `step`. |
| `value` | `GeomPoint[]` |  |  |

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-disabled` | Present when disabled. |
| `data-dragging` | Whether a point is being dragged. |

### Graph

The drawing surface, a 100×100 stretched viewBox: holds `Line` and `Fill`, and a double click on it adds a point. Carries `data-blocked` briefly when adding is refused at `maxPoints`. Renders a `<svg>` element.

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-disabled` | Present when disabled. |
| `data-dragging` | Whether a point is being dragged. |
| `data-blocked` | Briefly true after an add was refused at `maxPoints`. |

### Line

The envelope curve through the points. Renders a `<polyline>` element.

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-disabled` | Present when disabled. |
| `data-dragging` | Whether a point is being dragged. |

### Fill

The area under the curve. Renders a `<polyline>` element.

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-disabled` | Present when disabled. |
| `data-dragging` | Whether a point is being dragged. |

### Points

Renders one child per point, in `x` order.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `(point: GeomPoint, index: number, points: GeomPoint[]) => React.ReactNode` |  |  |

### Point

A draggable handle for the point at `index`, positioned with `left`/`bottom` percentages over the `Graph`. It is a `role="slider"` on the point's level (`y`): give it an `aria-label`. One point at a time is the tab stop; arrow keys move it (Shift for larger steps), Delete or a double click removes it. Carries `data-blocked` briefly when removal is refused at `minPoints`. Renders a `<div>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `getAriaValueText` | `(point: GeomPoint, index: number) => string` |  | Returns the point's `aria-valuetext`. Defaults to the formatted `x, y`. |
| `index` | `number` |  | Index of the point in the (sorted) value. |

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-disabled` | Present when disabled. |
| `data-dragging` | Whether a point is being dragged. |
| `data-blocked` | Briefly true after a removal was refused at `minPoints`. |
| `data-removable` | Whether the point can currently be removed. |

## Styled

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