Parameter Field

A numeric field for an audio parameter: a tempo, a gain, a transpose, a cutoff, a pan, a velocity. It reads as a DAW's does, the name at its start, the value in monospace figures, the unit after it, and every way in a DAW to change it.

Overview

• Typing: type a value and press Enter, or leave the field. What is typed stays in the field until it is committed, so a half-typed number never reaches onValueChange.
• Stepping: the arrow keys step by step, with Shift by largeStep and with Alt by smallStep; the Page keys by largeStep; Home and End go to min and max. steppers adds a minus and a plus either side. The wheel never changes the value.
• Scrubbing: drag the label or the unit sideways (scrub="horizontal", right is more) or up and down ("vertical", up is more), one step every scrubSensitivity pixels; hold Shift for large steps, Alt for small ones. The pointer is hidden while it drags, so it can go on past the screen's edge.
• Display: precision digits after the point (as many as step has by default, or as format says when it is given), and format for the rest, such as a sign (signDisplay) or a percent. Figures are not grouped (1200 Hz, not 1,200 Hz) unless format says so.

Installation

bunnpmpnpmyarn
Copy
pnpm dlx shadcn@latest add @audio-ui/parameter-field

Usage

Copy
import { ParameterField } from "@/components/audio-ui/parameter-field";

Uncontrolled: set only the initial value.

Copy
<ParameterField defaultValue={-6} label="Gain" max={24} min={-36} precision={1} step={0.1} unit="dB" />

Controlled: drive the value from state, and close an undo step when a gesture ends.

Copy
const [bpm, setBpm] = useState(120);

<ParameterField
  label="Tempo"
  max={999}
  min={20}
  onValueChange={setBpm}
  onValueCommitted={commitTempo}
  precision={2}
  steppers
  unit="BPM"
  value={bpm}
/>

Dense: size="sm" for a panel of many, and hideLabel where the label sits elsewhere; the label still names the field.

Copy
<ParameterField hideLabel label="Transpose" scrub="vertical" size="sm" unit="st" />

Text of its own: formatValue and parseValue write the value as text and read typed text back, such as a position in bars.beats.16ths, with the same look, keys and scrubbing. shortLabel shows a shorter word than the accessible name.

Copy
<ParameterField
  formatValue={(seconds) => formatBars(seconds, meter, "position")}
  label="Clip start"
  onValueChange={setStart}
  parseValue={(text) => parseBars(text, meter, "position")}
  shortLabel="Start"
  size="sm"
  step={sixteenth}
  value={start}
/>

API reference