Primitives

All primitives in @audio-ui/react share one structure. The Knob shows it, and the others follow the same pattern.

Parts

A primitive is a set of parts you assemble. Each part renders one element and does one job: the root owns the value, the control takes the pointer, the thumb takes the focus.

Copy
import { Knob } from "@audio-ui/react";

<Knob.Root defaultValue={50}>
  <Knob.Label>Cutoff</Knob.Label>
  <Knob.Control>
    <Knob.Track />
    <Knob.Indicator />
    <Knob.Thumb aria-label="Cutoff" />
  </Knob.Control>
  <Knob.Value />
</Knob.Root>

Nothing is painted: no colour, size or theme comes from a primitive. Each part sets only the inline styles its behaviour needs (touch-action on a drag surface, position: relative on a container that holds absolutely placed parts, pointer-events on decorations), and the look is yours. Parts you leave out are not rendered, so a knob with no value readout is a knob without Knob.Value.

Style from state

State is on the element, never behind a prop you have to read. Style it with the attribute selectors of your CSS or the variants of your framework:

Copy
<Knob.Thumb className="cursor-grab data-dragging:cursor-grabbing" />

• Attributes and variables. A part has data-disabled, data-dragging and the like when they are true, and no attribute when they are not. What changes too often to be an attribute is a CSS variable, such as a knob mark's angle or a timeline's unit. Headless styling lists both for every part.
• State functions. className and style can be functions of the part's state:

Copy
<Knob.Thumb className={(state) => (state.dragging ? "ring-2" : "ring-0")} />

Render another element

Every part takes a render prop to change the element it renders or to compose it with your own component. Its props, ref and handlers are merged with yours, not replaced:

Copy
<Knob.Control render={<MyDial />} />
<Timeline.Clip render={(props, state) => <article {...props} />} />

A handler you pass runs alongside the part's own. A consumer's onPointerDown does not switch the drag off.

Control the value

A primitive is uncontrolled with defaultValue, or controlled with value. Either way it tells you what changed and why:

Copy
<Knob.Root
  onValueChange={(value, eventDetails) => {
    if (eventDetails.reason === "wheel") {
      eventDetails.cancel(); // refuse this one
    }
  }}
  onValueCommitted={(value, eventDetails) => save(value)}
  value={cutoff}
/>

• onValueChange fires on every change, with eventDetails.reason ("drag", "wheel", "keyboard", "reset", "input-change"...) and eventDetails.event, the event behind it. eventDetails.cancel() refuses the change: a controlled value stays put, an uncontrolled one does not move.
• onValueCommitted fires once, when a gesture that changed the value ends. That is the time to start a note, push to an undo stack or save, not on every move of a drag.
• While a pointer drags, the part follows it even if your controlled value is late, and takes the value back when the pointer is released.

Live values

A playhead, a meter or a waveform that follows a signal changes sixty times a second, too often to go through React state. Give it a source instead, an object with getSnapshot and subscribe, and the part writes each value straight to the DOM:

Copy
import { createSource } from "@audio-ui/react";

const position = createSource(0);

// in your audio loop
position.set(audioContext.currentTime);

<Timeline.Root source={position}>
  <Timeline.Lane>
    <Timeline.Playhead />
  </Timeline.Lane>
</Timeline.Root>

Your page does not re-render while it plays.

Accessibility

Each control holds a native <input type="range">, visually hidden. It takes the focus, answers the arrow, Page, Home and End keys, announces its value and carries the accessible name, so a screen reader and the keyboard treat it as the slider it is. Give the thumb an aria-label, or a Label part, and format what is read out with getAriaValueText or format. Pointer presses do not draw the keyboard focus ring; keyboard focus does.

Import only what you use

Import from the root, or from a subpath to keep the rest out of your bundle:

Copy
import { Knob } from "@audio-ui/react/knob";

A single primitive weighs a few kilobytes gzipped (a knob about 5 KB, a fader about 3 KB).

Forms

The parameter controls are form fields. Give one a name and its native input submits with the form, so a preset can be a plain <form>:

Copy
<form action={savePreset}>
  <Knob.Root defaultValue={1000} name="cutoff">
    ...
  </Knob.Root>
  <Fader.Root defaultValue={40} max={100} name="gain">
    ...
  </Fader.Root>
  <XYPad.Root name="pad">...</XYPad.Root>
</form>

• Knob and Fader submit one number under their name. The Knob also takes form to belong to a form elsewhere in the page.
• XY Pad submits two, as pad.x and pad.y.
• The other primitives (Envelope, Plot, Sequencer, Pad, Piano, PianoRoll, Timeline, Waveform, Meter) hold a value that is not a single number, a curve or a pattern for instance, so they do not submit by themselves: read it from onValueChange or onValueCommitted and send it as you like.
• A disabled control is left out of the submission, as with any input.

The package

@audio-ui/react holds every primitive, each also its own entry point, @audio-ui/react/<primitive>, which ships that primitive alone. Each has its page in this section.

bunnpmpnpmyarn
Copy
pnpm add @audio-ui/react

Copy
import { createSource, adjacentPoint, Envelope, Fader, Knob, /* … */ } from "@audio-ui/react";