Fader

A linear control for continuous parameters such as volume, gain or a send level. The registry component wraps the Fader primitive from @audio-ui/react and adds size variants and thumb marks.

Overview

• Input: drag the thumb or press the track, or use the mouse wheel or the keyboard. onValueCommitted fires when the interaction ends.
• Layout: vertical by default, or horizontal, in sm, default and lg sizes.
• Display: a filled range and a thumb, with optional marks inside the thumb (thumbMarks).
• Accessibility: the thumb holds a native <input type="range"> that carries the accessible name (aria-label or aria-labelledby), the value text (formatted with format) and the form value (name).

Installation

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

Anatomy

Import the primitive and assemble its parts.

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

<Fader.Root>
  <Fader.Label />
  <Fader.Control>
    <Fader.Track>
      <Fader.Indicator />
    </Fader.Track>
    <Fader.Mark value={50} />
    <Fader.Thumb />
  </Fader.Control>
  <Fader.Value />
</Fader.Root>

Usage

Copy
import { Fader } from "@/components/audio-ui/fader";

Uncontrolled: set only the initial value.

Copy
<Fader defaultValue={0} max={6} min={-60} step={1} />

Controlled: drive the value from state.

Copy
const [gain, setGain] = useState(0);

<Fader
  max={6}
  min={-60}
  onValueChange={setGain}
  onValueCommitted={(value, details) => console.log("Committed:", value, details.reason)}
  step={1}
  value={gain}
/>

Interaction

Pointer

Keyboard

On the focused thumb:

Wheel

The mouse wheel over the fader moves the value by step and reports eventDetails.reason === "wheel".

API reference

Root

Groups all parts of the fader, with audio defaults (vertical, -60…+6) and mouse-wheel stepping. While a pointer drags it, the thumb follows the pointer even if a controlled value lags behind, as with a seek bar driven by playback time or automation. To reject a value, call eventDetails.cancel(). Renders a <div> element.

Control

The interactive area: pointer presses and drags, plus mouse-wheel stepping. Sets touch-action: none so touch drags don't scroll the page. Renders a <div> element.

Indicator

The filled part of the track: from min up to the value, or between the Root's anchor and the value, on whichever side of it the value is. Renders a <div> element.

Mark

A graduation along the track at value: placed from the start of the travel in the fader's direction, where the thumb's center would be at that value. It carries data-active while the value has reached it from the anchor, and data-orientation. Decorative: the thumb's input announces the value. Render your own tick and label inside it. Renders a <div> element.

Registry component

Fader accepts style props (size, thumbMarks, className) plus primitive props from FaderPrimitive.Root.Props (name, form, format, locale, largeStep, render, …). The primitive's Fader.Mark places a graduation at a value along the track, with data-active once the value has reached it, to build your own ruler. aria-label, aria-labelledby, and aria-describedby are forwarded to the thumb's input.

Value and state

Layout and visuals

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

Examples

Vertical (default)

Horizontal

Pan, filled from the center

anchor={0} makes the fill grow from the center of a -1…1 range, left or right of it.

Mixing console

A fader per channel in dB, from silent at the bottom to +6 dB, beside the meter of what it lets through.