Button
A button component for audio applications supporting both toggle (latch) and momentary modes with proper event handling.
The Button component provides a customizable button for audio applications. It shares the same layout, parameter model, interaction, and accessibility as other vector components; see the Vector introduction.
- Two operation modes: Latch (toggle) and momentary
- Full theming support: color, roundness customization
- Drag interactions: Proper handling of global mouse events to ensure reliable release behavior, and allow easy implementations of, for example, step sequencers and pads
Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
value | boolean | — | Yes | Current value of the button (true = pressed/active, false = released/inactive) |
onChange | (event: AudioControlEvent<boolean>) => void | — | No | Handler for value changes |
latch | boolean | false | No | Whether the button should latch (toggle between states) or momentary (only active while pressed). Ad-hoc mode only, ignored if parameter provided. |
label | string | — | No | Label displayed below the component |
color | string | — | No | Component primary color - any valid CSS color value |
roundness | number | — | No | Roundness for component corners (normalized 0.0-1.0) |
adaptiveSize | boolean | false | No | Whether the component stretches to fill its container |
size | "xsmall" | "small" | "normal" | "large" | "xlarge" | normal | No | Size of the component |
displayMode | "scaleToFit" | "fill" | scaleToFit | No | Layout mode for the control |
labelMode | "none" | "hidden" | "visible" | visible | No | Visibility of the label row |
labelPosition | "above" | "below" | below | No | Vertical position of the label relative to the control |
labelAlign | "start" | "center" | "end" | center | No | Horizontal alignment of the label text |
labelOverflow | "ellipsis" | "abbreviate" | "auto" | auto | No | How to handle label text overflow |
labelHeightUnits | number | — | No | Label height in the same units as SVG viewBox height |
parameter | BooleanParameter | — | No | Audio Parameter definition (Model). If provided, overrides label/latch from ad-hoc props |
paramId | string | — | No | Identifier for the parameter this control represents |
midiResolution | MidiResolution | 7 | No | MIDI resolution in bits (ad-hoc mode, ignored if parameter provided) |
onClick | React.MouseEventHandler | — | No | Click event handler |
onMouseDown | React.MouseEventHandler | — | No | Mouse down event handler |
onMouseUp | React.MouseEventHandler | — | No | Mouse up event handler |
onMouseEnter | React.MouseEventHandler | — | No | Mouse enter event handler |
onMouseLeave | React.MouseEventHandler | — | No | Mouse leave event handler |
className | string | — | No | Additional CSS classes |
style | React.CSSProperties | — | No | Additional inline styles |
Basic Usage
The Button component requires a value (boolean) and onChange handler. The button operates in two modes: latch (toggle) or momentary.
Latch Mode (Toggle)
In latch mode, the button toggles between pressed and released states:
Momentary Mode
In momentary mode, the button is only active while being pressed:
Modes of Operation
The Button component supports two modes of operation:
Ad-Hoc Mode (Props Only)
In ad-hoc mode, you provide individual props (label, latch, etc.) and the component creates the parameter model internally:
Strict Mode (Parameter Only)
In strict mode, you provide a full parameter model via the parameter prop. The following example uses ad-hoc props; with the full library you would use createBooleanParameter and the parameter prop:
Theming
Vector components share common theming features; see Theming Features in the Vector introduction for an overview. The Button component supports theming through the color and roundness props:
Color Customization
Roundness
Control the roundness of the button corners:
Adaptive Sizing
The Button 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.
Label Configuration
Control how the label is displayed:
Label Position
Label Alignment
Label Visibility
Event Handling
The Button component provides standard mouse event handlers:
Global Mouse Event Handling
The Button component handles global mouse events for momentary buttons to ensure reliable release behavior. This means that even if you drag the mouse outside the button before releasing, the button will still properly detect the release event.
This is particularly important for momentary buttons used in audio applications where precise timing is critical.
Common Patterns
Power Button
A typical power toggle button:
Record Button
A momentary record button:
Button Group
Multiple buttons in a group:
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:
Common Use Cases
Power Switch
Record Button
Effect Bypass
Next Steps
- Explore the CycleButton component for discrete option selection
- Learn about Knob and Slider for continuous controls
- Check out FilmStripBooleanControl or ImageSwitch for bitmap-based buttons
- Visit the playground for interactive examples