Primitive Components
Low-level building blocks for composing custom controls. These primitives provide the foundation for building audio and MIDI interfaces. SVG primitives handle rendering, control primitives handle interaction logic, and layout primitives manage responsive sizing and positioning. Use these to create custom components tailored to your specific needs.
Layout Primitives
AdaptiveBox
A CSS/SVG-based layout system for SVG controls with labels. Supports multiple display modes (scaleToFit, fill), container queries, two-row grid layout, label positioning, and HTML overlay support. The foundation for all control layouts.
SVG Primitives
ValueRing
An arc/ring indicator showing value progress. Supports bipolar mode, configurable thickness, openness, and roundness. The stroke expands inward from the radius, perfect for knob value indicators.
RotaryImage
Rotates children or an image based on normalized value. Shares angle logic with ValueRing via useArcAngle hook. Wraps RadialImage internally, ideal for rotating knob graphics and images.
FilmstripImage
Displays a specific frame from a bitmap sprite sheet (filmstrip) based on normalized value. Supports frame rotation and configurable frame dimensions, perfect for bitmap-based control visualization.
TickRing
A decorative primitive for rendering tick marks around radial controls. Supports count-based or step-based positioning, multiple variants (line, dot, pill), and custom render functions for advanced styling.
LabelRing
A wrapper primitive for rendering text or icon labels at radial positions. Supports numeric scales, text labels, icons, and configurable orientation (radial, upright). Perfect for knob scale labels.
LinearStrip
A linear rectangle strip for linear controls. Positioned at a center point (cx, cy) with configurable length, thickness, rotation, and rounded corners. Used for slider tracks, faders, and pitch/mod wheels.
ValueStrip
The active (foreground) portion of a linear strip. Renders the filled portion based on normalized value, supporting unipolar (fills from bottom) and bipolar (fills from center) modes. Used for slider value indicators and fader fills.
LinearCursor
A cursor that slides along a linear strip. Position driven by normalized value (0.0 = bottom, 1.0 = top). Supports image or SVG shape (rectangle/ellipse based on roundness). Rotates around strip center along with the virtual bar. Used for slider cursors and fader handles.
RadialImage
Displays static content at radial coordinates. The content is sized to fit within the specified radius and centered at (cx, cy). Can display an image or arbitrary SVG content, useful for icons or static images within knob compositions.
RadialHtmlOverlay
Renders HTML content inside an SVG at a radial position using foreignObject. Creates a square foreignObject centered at (cx, cy) with size based on radius. Preferred way to render text inside knobs, leveraging native HTML text rendering.
Image
Displays static content at rectangular coordinates. Positioned at (x, y) with specified width and height. Can display an image or arbitrary SVG content, designed for straightforward rectangular image placement without radial positioning.
RevealingPath
Reveals a path from start to end using CSS stroke-dashoffset. Uses SVG pathLength attribute to normalize path length calculation, enabling performant filling animations without JavaScript geometric calculations.
Control Primitives
ContinuousControl
A generic continuous control that connects a data model (AudioParameter) to a visualization view (ControlComponent). Handles parameter resolution, value management, interaction handling, and layout management for continuous controls like knobs and sliders.
DiscreteControl
A generic discrete control that connects a data model (DiscreteParameter) to a visualization view (ControlComponent). Handles parameter resolution, value management, interaction handling, and layout management for discrete controls like cycle buttons and selectors.
BooleanControl
A generic boolean control that connects a data model (BooleanParameter) to a visualization view (ControlComponent). Handles parameter resolution, value management, interaction handling, and layout management for boolean controls like buttons and toggles.
OptionView
A component for defining visual content for discrete control options. Used as children of DiscreteControl to provide ReactNodes (icons, styled text, custom components) for rendering. Matched to options by value in hybrid mode.