ImageRotarySwitch

A discrete control that rotates an image based on discrete option values, perfect for custom rotary switch designs using bitmap graphics.

ImageRotarySwitch is a discrete control that rotates an image based on discrete option values. 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 mapping the current value to a normalized position, with snapping to discrete positions based on the number of options.

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
valuestring | number—YesCurrent value of the control
onChange(event: AudioControlEvent<string | number>) => void—NoHandler for value changes
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)
adaptiveSizebooleanfalseNoWhether the component stretches to fill its container
size"xsmall" | "small" | "normal" | "large" | "xlarge"normalNoSize of the component
parameterDiscreteParameter—NoAudio Parameter definition (Model). If provided, overrides options/label from ad-hoc props
optionsArray<{ value: string | number; label?: string; midiValue?: number }>—NoArray of option definitions (strict mode)
childrenReact.ReactNode—NoOptionView children for ad-hoc or hybrid mode

Understanding Options vs Children

ImageRotarySwitch distinguishes between two concepts:

  • options prop: Defines the parameter model (value, label, midiValue). Used for parameter structure.
  • children (OptionView components): In this component, discrete visuals are handled by the raster image (rotation), not by OptionView content. OptionView here is mainly syntactic sugar: it populates the option set in ad-hoc mode (values and count); the component uses the number of OptionView children to derive rotation position. The visual content inside OptionView (e.g. text or icons) is never displayed.

These serve different purposes and can be used together: use options or a parameter when you have data-driven option definitions or need MIDI mapping; use OptionView children for simple, ad-hoc setups when you want the option set inferred from the children.

Note:

Basic use: For basic use of ImageRotarySwitch, and especially when using ad-hoc props (no parameter prop), prefer OptionView children. In that case the option set is inferred from the OptionViews. Use the options prop or a full parameter when you need explicit parameter structure (e.g. data-driven options, MIDI mapping). For a full disambiguation of options vs OptionView, see Options vs OptionView.

Basic Usage

ImageRotarySwitch requires an image URL and frame dimensions. Use OptionView children to define the discrete options:

BasicImageRotarySwitch.tsx

Modes of Operation

ImageRotarySwitch supports three modes of operation:

Ad-Hoc Mode (Children Only)

Model inferred from OptionView children:

AdHocImageRotarySwitch.tsx

Strict Mode (Parameter Only)

Model provided via parameter prop. The following example uses children (OptionView); with the full library you would use createDiscreteParameter and the parameter prop:

StrictModeImageRotarySwitch.tsx

Hybrid Mode (Parameter + Children)

Model from parameter, View from children (matched by value). Use the same pattern as Strict Mode with OptionView children when the parameter is not in scope.

HybridModeImageRotarySwitch.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

Position Mapping

The component maps discrete option values to rotation positions:

  • Option index 0 → Minimum rotation position
  • Option index N → Maximum rotation position
  • Intermediate positions are evenly distributed across the openness range

Adaptive Sizing

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

ImageRotarySwitchSizing.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.

ImageRotarySwitchAdaptiveSize.tsx

Common Use Cases

Volume Level Selector

VolumeLevelSelector.tsx

Tone Selector

ToneSelector.tsx

Multi-Position Selector

MultiPositionSelector.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, snapping to discrete positions

Rotation Calculation

The rotation angle is calculated as:

  • Option index maps to normalized position (0 to 1)
  • Normalized position maps to rotation range based on openness
  • rotation offset is added to align the image
  • Positions snap to discrete option values

Next Steps