ProControls for p5.js

Getting Started

Load the script file after p5.js, set ControlStyle, create controls in setup(), and call .draw() in draw(). Mouse, wheel, and touch events are wired automatically — no event handlers needed.

HTML setup

<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined&display=block" rel="stylesheet">
<script src="p5.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/dstein-art/proControls4p5js@master/ProControls.js"></script>
<script src="sketch.js"></script>

Minimal sketch

ControlStyle = 'black';  // set before creating controls

let vol, pan, pwr;

function setup() {
  createCanvas(600, 300);
  vol = new AnalogSlider({ x: 40,  y: 50, label: 'VOL' });
  pan = new Dial({         x: 120, y: 60, label: 'PAN' });
  pwr = new AnalogSwitch({ x: 220, y: 80, label: 'PWR', states: ['OFF', 'ON'] });
}

function draw() {
  proControlBackground();  // style-matched background
  // Controls render themselves — no draw loop needed.
}

// No event handlers. No draw loop. Controls self-register and self-draw.

Rebuilding controls at runtime

When recreating all controls (e.g. on a style switch), call proControlReset() first to clear stale registrations. Read current values before rebuilding to preserve them.

function buildControls() {
  proControlReset();              // clear old registrations
  ControlStyle = currentStyle;
  mySlider = new AnalogSlider({ value: mySlider?.value ?? 0.5 });
}

Removing a single control

mySlider.remove(); // deregisters from events; stop calling .draw() to remove visually

Common options (all controls)

Every control inherits these from the ProControl base class.

AnalogSlider Input

A vertical fader with a draggable cap, optional scale ticks, and a live readout. Drag the cap or scroll the mouse wheel to change value. Double-click the cap to reset to the initial value.

Options

Example

Slider styles

Set style on any vertical AnalogSlider to change its visual. Interaction is identical across all styles.

wheel — a cylinder visible through a slot. Ribs scroll with the value position; center notches mark the midpoint. Vertical: horizontal ribs, width defaults to 50px. Horizontal: vertical ribs, full slot is draggable. Scale defaults to off.

button — a minimal thin-groove track with a spherical circular cap. Works in both orientations. Width defaults to 40px and scale defaults to off.

MultiSlider Input

Several AnalogSlider faders arranged side-by-side in a single unit — useful for equalizers, mixer channel strips, or any bank of related faders. A single onChange/onRelease fires whenever any child slider changes, receiving a name → value object covering all sliders at once.

Options

Properties & methods

Per-slider overrides

Pass an object instead of a plain number for any slider to override shared options for that specific channel.

const eq = new MultiSlider({
  x: 20, y: 40, height: 180,
  min: -12, max: 12, readout: 'raw', decimals: 1,
  sliders: {
    '60Hz':  0,           // plain number → uses shared min/max
    '250Hz': 0,
    '2kHz':  { value: 3, theme: { capIndicator: '#ff6600' } }, // object → per-slider overrides
    '8kHz':  0,
  },
  onChange:  v => console.log('eq changed', v),
  onRelease: v => console.log('eq released', v),
});

Example — vertical (default)

Example — horizontal with a spring-back override on one slider

RangeSlider Input

A fader with two draggable caps that define a low/high range. Drag either cap independently; caps constrain each other so they never cross. The region between the caps is filled with the accent colour. Scroll-wheel adjusts the cap nearest the cursor. Double-click a cap to reset it to its initial value.

Options

Properties

Example — vertical

Example — horizontal

Dial Input

A rotary knob with a 270° arc sweep. Drag up/down or scroll the mouse wheel to turn it. A tooltip shows the live value while dragging. Double-click to reset to the initial value.

Options

Example

Dial styles

Set style to choose a knob visual. All styles share the same interaction and arc track — only the knob body rendering changes.

MultiDial Input

Several Dial knobs arranged side-by-side in a single unit. A single onChange/onRelease fires whenever any dial changes, receiving a name → value object. A raised bevel panel frames the group. All dials share options by default; individual dials can override with per-dial objects.

Options

Properties & methods

Example — horizontal row (default)

Example — vertical column with an individual dial override

Pads Input

XYPad Input

A two-axis drag surface. Click or drag to set X and Y values independently. Fires separate callbacks per axis. Y increases upward to match musical convention. Double-click to reset both axes to their initial values.

Options

Example

Example — spring back to center

GridPad Input

A 2-D grid of cells with four modes: toggle flips each cell 0 ↔ 1 on click; percent raises or lowers each cell's 0–1 value while the mouse is held; button treats each cell as a momentary key with press/release callbacks and no stored value; colorselect cycles each cell through a list of colours on each click, with each colour mapped to a semantic value. Optional horizontal and vertical grouping draws a bevel separator every N cells. Double-click the label to reset all cells to their initial values.

Options

Interaction — toggle mode

Interaction — percent mode

Interaction — button mode

Interaction — colorselect mode

Public API

Example — toggle mode (step sequencer)

Example — percent mode (velocity matrix)

Example — colorselect mode

Selectors Input

Switch Input

An illuminated discrete selector. Two states renders as a rocker toggle — click to flip. Three or more states renders as a vertical button stack — click any slot to select it. The active slot glows with the style's accent color. Double-click any slot or the label to reset to the initial state.

Options

Reading state

sw.state            // active index (readable/writable)
sw.states[sw.state]  // active label string

Two-state rocker

N-state selector

IconButton Input

A square push button that renders a Material Symbols icon at its centre. Pass any icon name from the Material Symbols Outlined set as the icon option — the font is already included via the page's <link> tag. Supports momentary (default) and toggle modes. An optional text label is drawn inside the button below the icon.

Options

Properties

Example

Selector Input

A multi-style option selector. Set style to choose the visual style. Scroll wheel and touch work for all styles. Double-click the selection display or the label to reset to the initial option (double-clicking the arrow buttons or gear wheel advances state as normal).

Options

Properties

Style — rotary (default)

A mechanical drum-style selector inspired by vintage rotary counters. A display window shows the selected option; the drum's serrated edge is exposed on the right — horizontal ridges scroll as the drum rotates, giving a tactile feel. Adjacent options are visible while scrolling. Drag up/down, scroll wheel, or touch.

Style — arrow

A compact left/right arrow selector. Pressing either arrow button steps to the adjacent option; the new selection slides into the display window from the direction of travel. Scroll wheel also works.

TagSelector Input

A multi-select chip panel. Each string in words is displayed as a rounded pill inside a box. Click any pill to toggle its selection; multiple pills can be selected simultaneously. Double-click the label to reset to the initial selection.

Options

Properties

Example

SliderSelector Input

A vertical fader that snaps to discrete string options. It looks and behaves like an AnalogSlider — same panel, track, and brushed-metal cap — but instead of a continuous numeric range the slider clicks into one of the provided option strings. Tick marks at each position are drawn to the right of the track, and the active option's tick and label are highlighted in the accent colour. Scroll-wheel steps through options when hovering.

Options

Properties

Interaction

Example

Panel Container

A clipping container that groups ProControls into a positioned, optionally scrollable surface. Controls added with .add() are positioned relative to the panel's top-left corner — a slider at (10, 10) appears 10px from the panel edge, not the canvas edge. When child controls extend beyond the panel bounds, thin scrollbars appear automatically; the scroll wheel pans the view when no child control is hovered.

Constructor options

Methods & properties

onChange / onRelease / values

When onChange or onRelease are set, the panel listens to every child control and fires the respective callback — with a single snapshot object — on change or release. The same object is always available via panel.values.

Field names are derived from each control's label option with spaces and punctuation stripped (e.g. "Low Cut" → LowCut). Controls without a label are named by class and a per-class counter: the first unlabelled AnalogSlider becomes AnalogSlider1, the second AnalogSlider2, and so on. MultiSlider and MultiDial follow the same rule — the slider/dial keys within their own values object also have spaces and punctuation stripped from the label.

Values per control type:

Note: set any per-control onChange callbacks before calling panel.add(). Callbacks assigned after add() will work for the individual control but the panel notification will wrap the value that was set at add-time.

Scrolling

Scrollbars appear automatically when children extend beyond the panel boundaries. The scroll wheel scrolls the panel when the pointer is over the panel but not over a focused child control. If a child control (e.g. a Dial) is hovered, the scroll wheel is forwarded to that child instead. You can also drag the scrollbar thumbs directly.

Example — onChange

Example — grouped controls

Example — scrollable content

MessageDialog Container

A self-sizing, movable dialog that displays a formatted text message and optional action buttons. The message string is word-wrapped to fit the dialog width. Buttons are arranged in a single row at the bottom; if multiple buttons are provided the dialog widens automatically to fit them all on one line. Drag the title bar to reposition.

Options

Properties

Example

InputDialog Container

Extends MessageDialog with a single-line text input field between the message and the buttons. Clicking the input field captures keyboard events for typing, cursor movement, and editing. The cursor blinks and the text scrolls horizontally when the value overflows the field width. Pressing Enter fires onSubmit; clicking outside the field removes focus.

Options

Properties

Keyboard interaction

Example

Menu Input

A menu bar that runs either along the top (orientation: 'horizontal') or down the left side (orientation: 'vertical'). Items are defined as an array of strings; replace any string with an array to create a submenu — the first element of the array becomes the top-level label and the remaining elements are the submenu entries. Clicking a leaf item fires onChange; clicking a submenu parent toggles it open or closed.

Options

Properties

Example — top

Example — left

Displays

Read-only meters and display panels. Assign .value (or individual properties) each frame to drive them — no event wiring required.

VUMeter Display

Extends AnalogSlider. Overlays a segmented LED column (green → yellow → red) with peak hold on top of the fader track. Drive it each frame by assigning .value from audio analysis.

Additional options

Example

VUDial Display

Extends Dial. Replaces the filled arc with a ring of segmented LEDs with peak hold. Use showKnob: false for a pure meter ring, or true to show both the set position and the live level.

Additional options

Example

LEDMeter Display

A 7-segment numeric display. Segments are drawn as beveled hexagons with a canvas glow. Values are right-aligned; if the number is too wide for the digit slots, all segments show -----. Assign .value each frame.

Options

Example

ADSRDisplay Display

A display-only ADSR envelope graph inside a beveled panel. The envelope shape updates live whenever any property changes — pair it with dials or sliders to visualise synth parameters in real time.

Options

Visual layout

Attack, Decay, and Release are displayed proportionally across 70% of the plot width. The sustain hold occupies the remaining 30% as a fixed visual segment. A, D, S, R labels appear below each segment; dashed dividers mark the phase boundaries.

Example

Markup Display

A scrollable text panel that renders a subset of Wiki Markup syntax — headings, bold, italic, bullet and numbered lists, indented blocks, horizontal rules, and links. Set text at any time to update the content; the panel re-parses and scrolls to the top automatically.

Options

Properties

Wiki Markup syntax

Scrolling

When content is taller than the panel, a thin scrollbar appears on the right edge. Scroll with the mouse wheel while hovering the panel. Set scrollY programmatically to jump to any position.

Example

ConsolePanel Display

A floating, scrollable log panel that intercepts console.log, console.warn, console.error, and console.info calls as well as uncaught runtime errors and unhandled promise rejections. Messages are color-coded by type, timestamped, and always auto-scroll so the most recently added line is visible at the bottom. Consecutive identical messages (same type and text) are collapsed into a single entry showing the repeat count and the most recent timestamp — e.g. [12:04:31 ×5] redraw tick. A CLR button clears the log; a −/+ toggle minimizes the panel to just its title bar. The panel is movable, resizable, and minimizable by default.

Options

Properties & methods

Message colors

Interaction

Example

TimeGraphPanel Display

A scrolling time-series line graph panel. Push data points each frame to plot them against time — the oldest point scrolls off the left edge as new ones arrive on the right. Pass a plain number to plot a single variable, or an object ({key: value, …}) to plot multiple named variables simultaneously, each drawn in its own color with a legend. Y-axis range is auto-scaled to the data with 8% padding, or fixed by setting min and max. The panel is movable, resizable, and minimizable by default.

Options

Properties & methods

Example — single variable

Example — multiple variables

Themes & Styles

Set ControlStyle before creating controls. The style is captured at construction time, so controls built before a change keep their original look.

ControlStyle = 'brushed'; // before any new controls

Built-in styles

proControlBackground()

Use instead of p5's background(). Fills the canvas with the style color. 'brushed' and 'stainless' also draw per-row texture overlays via the native Canvas 2D API.

Runtime style switching

Rebuild controls with proControlReset() when switching styles. The Live Demo uses an AnalogSwitch to cycle all four styles.

const STYLES = ['black', 'stainless', 'white', 'brushed', 'dimpled', 'red', 'blue', 'yellow'];
const LABELS = ['BLACK', 'STEEL', 'WHITE', 'BRUSH', 'DIMPL', 'RED', 'BLUE', 'YLW'];
let currentStyle = 'black';

function buildControls() {
  proControlReset();
  ControlStyle = currentStyle;
  mySlider    = new AnalogSlider({ value: mySlider?.value ?? 0.5 });
  styleSwitch = new AnalogSwitch({
    states: LABELS,
    state:  STYLES.indexOf(currentStyle),
    label:  'STYLE',
    onChange: i => { currentStyle = STYLES[i]; buildControls(); },
  });
}

Per-control theme overrides

Pass a partial theme object to override individual color keys while keeping the rest of the active style.

new Dial({ label: 'MASTER', theme: { capIndicator: '#ffcc00' } });

Touch & Events

All mouse, wheel, touch events, and rendering are handled automatically by the library. No event functions and no draw loop are needed in your sketch. touch-action: none is applied to the canvas automatically to prevent iOS scroll conflicts.

How it works

Each control self-registers on construction into a shared array. Two p5.prototype.registerMethod hooks handle everything: a 'pre' hook fires at the start of every frame to dispatch mouse/wheel/touch events; a 'post' hook fires at the end of every frame and draws any control that wasn't already drawn explicitly that frame. This means you can still call c.draw() manually for z-order control — the post hook simply skips controls already rendered.

Coexisting with your own handlers

Registered library methods and sketch-level event functions both fire independently — they don't conflict. You can still define mousePressed() in your sketch for other logic.