ImageKnob

A continuous control that rotates an image based on a normalized value, perfect for custom knob designs using bitmap graphics.

ImageKnob is a continuous control that rotates an image based on a normalized value. It shares the same layout, parameter model, interaction, and accessibility as other controls (vector, raster, and control primitives); see the Raster introduction.

The image rotation is determined by the normalized value (0-1 maps to rotation based on openness and rotation offset).

Note:

No Theming Support: This component does NOT support themable props (color, roundness, thickness) as visuals are entirely determined by the image content.

Props

NameTypeDefaultRequiredDescription
valuenumber—YesCurrent value of the control
onChange(event: AudioControlEvent<number>) => void—NoHandler for value changes
minnumber—NoMinimum value (ad-hoc mode)
maxnumber—NoMaximum value (ad-hoc mode)
stepnumber—NoStep size for value adjustments
bipolarbooleanfalseNoWhether the component should operate in bipolar mode (centered at zero)
labelstring—NoLabel displayed below the component
frameWidthnumber—YesWidth of the viewBox (determines viewBox width)
frameHeightnumber—YesHeight of the viewBox (determines viewBox height)
imageHrefstring—YesURL to the image to rotate
rotationnumber0NoOptional rotation angle offset in degrees
opennessnumber90NoOpenness of the arc in degrees (value between 0-360º; 0º closed, 90º 3/4 open, 180º half-circle)
valueAsLabel"labelOnly" | "valueOnly" | "interactive"labelOnlyNoControls how the label and value are displayed
adaptiveSizebooleanfalseNoWhether the component stretches to fill its container
size"xsmall" | "small" | "normal" | "large" | "xlarge"normalNoSize of the component
parameterContinuousParameter—NoAudio Parameter definition (Model). If provided, overrides min/max/step/label/bipolar from ad-hoc props
valueFormatter(value: number, parameterDef: AudioParameter) => string | undefined—NoCustom renderer for the value display
interactionMode"drag" | "wheel" | "both"bothNoInteraction mode
interactionDirection"vertical" | "horizontal" | "circular" | "both"—NoDirection of interaction
interactionSensitivitynumber—NoSensitivity multiplier for interactions (default varies by control type)

Basic Usage

ImageKnob requires an image URL and frame dimensions:

BasicImageKnob.tsx

Rotation Configuration

Openness

Control the rotation range using the openness prop:

Openness.tsx

Rotation Offset

Apply a rotation offset to align the image:

RotationOffset.tsx

Parameter Model

Use a parameter model for integration with audio parameter systems. The following example uses ad-hoc props; with the full library you would use createContinuousParameter and the parameter prop:

ImageKnobParameterModel.tsx

Adaptive Sizing

The ImageKnob 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:

ImageKnobSizing.tsx

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.

ImageKnobAdaptiveSize.tsx

Interaction Modes

Control how users interact with the knob:

ImageKnobInteraction.tsx

Common Use Cases

Volume Knob

VolumeKnob.tsx

Tone Knob

ToneKnob.tsx

Direction Indicator

DirectionIndicator.tsx

Image Requirements

  • Format: Any image format supported by browsers (PNG, JPG, SVG, etc.)
  • Dimensions: The frameWidth and frameHeight props determine the viewBox dimensions
  • Aspect Ratio: The image will be scaled to fit the viewBox while preserving aspect ratio
  • Rotation: The image rotates around its center point based on the normalized value

Rotation Calculation

The rotation angle is calculated as:

  • Normalized value (0-1) maps to rotation range based on openness
  • rotation offset is added to align the image
  • For bipolar mode, the rotation is centered around the midpoint

Next Steps