ImageSwitch

A boolean control that displays one of two images based on state, perfect for on/off switches and buttons with custom bitmap graphics.

ImageSwitch is a boolean control that displays one of two images based on the boolean 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 displayed is determined by the boolean value:

  • false (normalized 0.0) displays imageHrefFalse
  • true (normalized 1.0) displays imageHrefTrue

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
valueboolean—YesCurrent value of the control
onChange(event: AudioControlEvent<boolean>) => void—NoHandler for value changes
latchbooleanfalseNoWhether the button operates in latch (toggle) mode or momentary mode
labelstring—NoLabel displayed below the component
frameWidthnumber—YesWidth of the viewBox (determines viewBox width)
frameHeightnumber—YesHeight of the viewBox (determines viewBox height)
imageHrefFalsestring—YesURL to the image for false/off state
imageHrefTruestring—YesURL to the image for true/on state
adaptiveSizebooleanfalseNoWhether the component stretches to fill its container
size"xsmall" | "small" | "normal" | "large" | "xlarge"normalNoSize of the component
parameterBooleanParameter—NoAudio Parameter definition (Model). If provided, overrides label/latch from ad-hoc props

Basic Usage

ImageSwitch requires two image URLs (one for off state, one for on state) and frame dimensions:

BasicImageSwitch.tsx

Modes of Operation

Latch Mode (Toggle)

In latch mode, the button toggles between pressed and released states:

LatchImageSwitch.tsx

Momentary Mode

In momentary mode, the button is only active while being pressed:

MomentaryImageSwitch.tsx

Image Selection

The component displays different images based on the boolean value:

ImageSelection.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 createBooleanParameter and the parameter prop:

ImageSwitchParameterModel.tsx

Adaptive Sizing

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

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

ImageSwitchAdaptiveSize.tsx

Common Use Cases

Favorite/Star Button

FavoriteButton.tsx

Power Switch

PowerSwitch.tsx

Momentary Record Button

RecordButton.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: Images will be scaled to fit the viewBox while preserving aspect ratio
  • States: Provide two separate images for off and on states

Image Selection Logic

The component selects images based on the boolean value:

  • value === false → Displays imageHrefFalse
  • value === true → Displays imageHrefTrue

The selection is immediate and does not animate between states.

Next Steps