Knob

The Knob component provides a circular control for continuous value adjustment. It shares the same layout, parameter model, interaction, and accessibility as other vector components; see the Vector introduction.

• Multiple visual variants: abstract, simplest, plainCap, iconCap
• Full theming support: color, roundness, thickness customization

Props

Basic Usage

The Knob component requires a value and onChange handler. In ad-hoc mode, you provide min and max to define the value range:

Variants

The Knob component supports four visual variants, each with a distinct appearance:

Simplest

A simplified version with minimal visual elements:

Abstract

The default variant with a clean, minimal design. Displays the current value as text in the center:

PlainCap

A variant with a plain cap design:

IconCap

The iconCap variant allows you to display custom SVG content (typically icons) at the center of the knob. The icon can rotate with the knob value or remain static:

The rotaryOverlay prop controls whether the icon rotates with the knob value (true) or remains static (false). The icon inherits color via currentColor, so it adapts to light/dark mode automatically. The example above matches the LFO knob from the AudioUI playground (iconCap with SquareWaveIcon); the playground provides sine, triangle, square, and saw wave icons you can reuse.

Theming

Vector components share common theming features; see Theming Features in the Vector introduction for an overview. The Knob component supports theming through the color and roundness props, or via the global theme system:

Color Customization

You can customize the knob's primary color using the color prop:

Roundness

Control the roundness of the knob's corners:

Thickness

Adjust the stroke thickness of the knob ring:

Ring Configuration

Openness

The openness prop controls how much of the ring is visible. It accepts values in degrees (0-360º):

• 0º: Closed ring (full circle)
• 90º: 3/4 open (default)
• 180º: Half-circle
• 270º: 1/4 open

Rotation

The rotation prop allows you to offset the starting angle of the ring:

Value Display

The valueAsLabel prop controls how the label and value are displayed:

• "labelOnly": Always shows the label (default)
• "valueOnly": Always shows the value
• "interactive": Shows label normally, but temporarily swaps to value during interaction

Bipolar Mode

In bipolar mode, the knob visualizes values relative to a center point rather than from minimum to maximum. This is useful for controls like pan or balance:

Value Formatting

You can customize how values are displayed using the valueFormatter prop. AudioUI provides built-in formatters for common audio parameters:

Parameter Model

Instead of using ad-hoc props (min, max, label), you can provide a full parameter model via the parameter prop. This is useful when integrating with audio parameter systems:

Copyimport { Knob, createContinuousParameter } from "@cutoff/audio-ui-react";
 
const cutoffParam = createContinuousParameter({
  paramId: "cutoff",
  label: "Cutoff",
  min: 20,
  max: 20000,
  unit: "Hz",
  scale: "log",
  defaultValue: 1000,
});
 
export default function ParameterModelExample() {
  const [value, setValue] = useState(1000);
 
  return (
    <Knob
      parameter={cutoffParam}
      value={value}
      onChange={(e) => setValue(e.value)}
    />
  );
}

Adaptive Sizing

The Knob component supports both fixed sizes and adaptive sizing. By default, the size of the component is driven by the Size System and their size attribute:

Adaptive sizing allows the component to adapt to the size of its parent container, adjusting its dimensions intelligently without causing distortion (scaleToFit display mode). The fill display mode makes the component fill the entire container, potentially distorting it.

Interaction Modes

Control how users interact with the knob:

You can also adjust the sensitivity of interactions:

Common Use Cases

Audio Filter Control

Volume Control

Pan Control

Next Steps

• Explore the Slider component for linear controls
• Learn about Button and CycleButton for discrete interactions
• Check out ImageKnob for custom bitmap-based knobs
• Visit the playground for interactive examples