# XYPad

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

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

```ts
import { XYPad } from "@audio-ui/react/xypad";
```

| Export | Kind | What it is |
| --- | --- | --- |
| `XYPad.Control` | function | The pad surface: a press jumps the value to the pointer and a drag follows it; the mouse wheel / trackpad moves it too. |
| `XYPad.Label` | function | Accessible label, associated with both axis inputs. |
| `XYPad.Root` | function | Groups all parts of the pad and owns its two-dimensional value. |
| `XYPad.Thumb` | function | Marks the value on the pad (`left`/`top` as percentages, centered with `translate`). |
| `XYPad.Value` | function | The formatted value (`format`/`locale` on Root), `"x, y"` by default. |

## Anatomy

Import the primitive and assemble its parts.

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

<XYPad.Root>
  <XYPad.Label />
  <XYPad.Control>
    <XYPad.Thumb />
  </XYPad.Control>
  <XYPad.Value />
</XYPad.Root>
```

## API reference

### Root

Groups all parts of the pad and owns its two-dimensional value. Exposes the value position as CSS variables for crosshairs and guides: `--xy-pad-x` (from the left) and `--xy-pad-y` (from the top), as percentages. Renders a `<div>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `Point` |  | Uncontrolled starting value. Defaults to the center of the pad. |
| `disabled` | `boolean` |  |  |
| `format` | `Intl.NumberFormatOptions` |  | Formats each axis for `XYPad.Value` and the inputs' `aria-valuetext`. |
| `locale` | `Intl.LocalesArgument` |  |  |
| `maxX` | `number` | `100` |  |
| `maxY` | `number` | `100` |  |
| `minX` | `number` | `0` |  |
| `minY` | `number` | `0` |  |
| `onValueChange` | `(value: Point, eventDetails: ChangeEventDetails) => void` |  | Fires on every change: press, drag, keyboard, wheel and input changes. |
| `onValueCommitted` | `(value: Point, eventDetails: CommitEventDetails) => void` |  | Fires when an interaction ends with a new value. |
| `stepX` | `number` | `1` |  |
| `name` | `string` |  | Names the pad for a form: its two inputs submit as `name.x` and `name.y`. |
| `stepY` | `number` | `1` |  |
| `value` | `Point` |  |  |

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-disabled` | Present when disabled. |
| `data-dragging` | Whether a pointer is dragging on the pad. |

### Control

The pad surface: a press jumps the value to the pointer and a drag follows it; the mouse wheel / trackpad moves it too. Sets `touch-action: none` so touch drags don't scroll the page. Renders a `<div>` element.

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-disabled` | Present when disabled. |
| `data-dragging` | Whether a pointer is dragging on the pad. |

### Thumb

Marks the value on the pad (`left`/`top` as percentages, centered with `translate`). Holds two native `<input type="range">`s, one per axis: the X input takes focus, both carry the accessible name, and the arrow keys move both axes. Renders a `<div>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `getAriaLabel` | `(axis: Axis) => string` |  | Names each axis input. Defaults to `aria-label` followed by "X" / "Y". |
| `getAriaValueText` | `(formattedValue: string, value: number, axis: Axis) => string` |  | Returns an axis input's `aria-valuetext`. Defaults to the formatted value. |

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-disabled` | Present when disabled. |
| `data-dragging` | Whether a pointer is dragging on the pad. |

### Value

The formatted value (`format`/`locale` on Root), `"x, y"` by default. Renders a `<output>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `\| React.ReactNode \| ((formattedX: string, formattedY: string, value: Point) => React.ReactNode)` |  |  |

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-disabled` | Present when disabled. |
| `data-dragging` | Whether a pointer is dragging on the pad. |

### Label

Accessible label, associated with both axis inputs. Renders a `<div>` element.

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-disabled` | Present when disabled. |
| `data-dragging` | Whether a pointer is dragging on the pad. |

## Styled

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