0

XY Pad

Previous Next

An XY pad component for controlling two parameters simultaneously. Perfect for synthesizers, filters, and effects that need two-dimensional control.

Loading...

<script lang="ts">
  import { XYPad } from "$lib/components/ui/audio/elements/xypad/index.js";
</script>
 
<XYPad defaultValue={{ x: 50, y: 50 }} class="aspect-square" />

Installation

pnpm dlx shadcn-svelte@latest add https://svelte-audio-ui.vercel.app/r/xypad.json

Usage

<script lang="ts">
  import { XYPad } from "$lib/components/ui/audio/elements/xypad/index.js";
</script>

Basic XY Pad

<XYPad defaultValue={{ x: 50, y: 50 }} />

Custom Value Display

Loading...

<script lang="ts">
  import { XYPad } from "$lib/components/ui/audio/elements/xypad/index.js";
</script>
 
<XYPad
  defaultValue={{ x: 50, y: 50 }}
  class="aspect-square"
  formatValue={(val) => `X: ${val.x}, Y: ${val.y}`}
  maxX={100}
  maxY={100}
  minX={0}
  minY={0}
/>

Hide Value Display

Loading...

<script lang="ts">
  import { XYPad } from "$lib/components/ui/audio/elements/xypad/index.js";
</script>
 
<XYPad
  defaultValue={{ x: 50, y: 50 }}
  showValueDisplay={false}
  maxX={100}
  maxY={100}
  minX={0}
  minY={0}
  class="aspect-square"
/>

API Reference

XYPad

Props

Prop Type Default Description
value { x: number; y: number } - Controlled value.
defaultValue { x: number; y: number } { x: 50, y: 50 } Uncontrolled default value.
size "sm" | "default" | "lg" | "xl" "default" Size variant (affects height).
disabled boolean false Disables interaction and lowers opacity.
label string - Optional text label rendered above the pad.
showValueDisplay boolean true Whether to show the value display overlay.
formatValue (value: { x: number; y: number }) => string - Custom formatter for the value text.
class string - Additional CSS classes for the root element.
onValueChange (value: { x: number; y: number }) => void - Callback when value changes during interaction.
onValueCommit (value: { x: number; y: number }) => void - Callback when value is committed (on release).

Examples

Synthesizer Control

Loading...

<script lang="ts">
  import { XYPad } from "$lib/components/ui/audio/elements/xypad/index.js";
</script>
 
<XYPad
  defaultValue={{ x: 30, y: 70 }}
  class="aspect-square"
  formatValue={(v) => {
    const freq = Math.round(20 + (v.x / 100) * 20_000);
    const cutoff = Math.round(200 + (v.y / 100) * 8000);
    return `${freq}Hz, ${cutoff}Hz`;
  }}
/>

Filter Control

Loading...

<script lang="ts">
  import { XYPad } from "$lib/components/ui/audio/elements/xypad/index.js";
</script>
 
<XYPad
  class="aspect-square"
  defaultValue={{ x: 50, y: 50 }}
  formatValue={(val) => `Freq: ${val.x}%, Res: ${val.y}%`}
/>

Notes

Important Information:

  • Native Implementation: This component is built as a pure Svelte implementation, providing a high-quality, accessible XY pad control without bulky dependencies.
  • Grid Display: The pad includes a visual grid to help with positioning.
  • Crosshair: Visual crosshairs indicate the current X and Y positions.
  • Value Display: By default, a value display overlay shows the current position. You can customize the formatter function or hide it entirely.
  • Size Variants: Four size variants are available (sm, default, lg, and xl). These effectively control the pad height.
  • Keyboard Support: Arrow keys adjust the value by 1. Holding Shift while using arrow keys changes the step amount to 10. y = 100 maps to the top of the pad following standard musical conventions.