XY Pad

"use client";

import { useState } from "react";

XY pad for simultaneous control of two values (for example filter cutoff/resonance, pan/mix, or macro controls). The registry component wraps XYPad primitives from @audio-ui/react and provides ready-to-use visuals (grid, crosshair, cursor, value display).

Overview

• Interaction model: Pointer drag, wheel nudging, and keyboard nudging over both axes.
• Axes: Independent ranges and steps for X (minX, maxX, stepX) and Y (minY, maxY, stepY).
• Feedback: Grid lines, crosshair, animated cursor, and optional value display overlay.
• Accessibility: Focusable interactive surface with ARIA labeling (aria-label / aria-labelledby).

Installation

bunnpmpnpmyarn
pnpm dlx shadcn@latest add @audio/xypad
Copy

Usage

import { XYPad } from "@/components/audio/xypad";

Uncontrolled - initial value only:

<XYPad
  defaultValue={{ x: 0, y: 0 }}
  maxX={100}
  maxY={1}
  minX={-100}
  minY={-1}
  stepX={1}
  stepY={0.01}
/>

Controlled - drive value from state:

const [position, setPosition] = useState({ x: 50, y: 50 });
 
<XYPad
  maxX={100}
  maxY={100}
  minX={0}
  minY={0}
  onValueChange={setPosition}
  onValueCommit={(value) => console.log("Committed:", value)}
  value={position}
/>

Interaction

Pointer

Keyboard

Focused XY pad:

Wheel

When focused, wheel deltas nudge both axes according to pad dimensions and axis ranges, then quantize with stepX and stepY.

API reference

XYPad accepts style props (size, formatValue, valueDisplay, className) plus primitive props from XYPadPrimitive.RootProps.

Value and state

Layout and display

Additional valid HTML attributes passed to XYPad.Root are forwarded.

Examples

Live value readout

"use client";

import { useState } from "react";

Size variants

sm

import { XYPad } from "@/components/audio/elements/xypad";

export function XYPadSizeSmDemo() {

default

import { XYPad } from "@/components/audio/elements/xypad";

export function XYPadSizeDefaultDemo() {

lg

import { XYPad } from "@/components/audio/elements/xypad";

export function XYPadSizeLgDemo() {

xl

import { XYPad } from "@/components/audio/elements/xypad";

export function XYPadSizeXlDemo() {

Disabled state

import { XYPad } from "@/components/audio/elements/xypad";

export function XYPadDisabledDemo() {

Custom formatted display

"use client";
import { XYPad } from "@/components/audio/elements/xypad";

Hidden value display

"use client";
import { XYPad } from "@/components/audio/elements/xypad";

Bipolar ranges (pan and mix style)

"use client";

import { useState } from "react";

Live value vs committed value callbacks

"use client";

import { useState } from "react";

Channel strip

Filter pad

"use client";

import { useState } from "react";

Reverb pad

"use client";

import { useId, useState } from "react";