ProControls — Documentation

New here? See the Getting Started page for HTML setup, script tags, a minimal sketch, and the common options table.

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.

new IconButton(opts)

Material Symbols font required. Add this to your <head>:
<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined&display=block" rel="stylesheet">

Options

Option	Type	Default	Description
icon	string	'star'	Material Symbols icon name. Full list at fonts.google.com/icons. Popular examples: `play_arrow`, `pause`, `stop`, `skip_next`, `skip_previous`, `fast_forward`, `fast_rewind`, `replay`, `shuffle`, `repeat`, `volume_up`, `volume_off`, `mic`, `mic_off`, `headphones`, `settings`, `tune`, `equalizer`, `graphic_eq`, `piano`, `favorite`, `star`, `bookmark`, `thumb_up`, `thumb_down`, `add`, `remove`, `close`, `check`, `edit`, `delete`, `save`, `upload`, `download`, `share`, `search`, `home`, `menu`, `info`, `warning`, `lock`, `lock_open`, `visibility`, `visibility_off`, `zoom_in`, `zoom_out`, `fullscreen`, `fullscreen_exit`, `refresh`, `power_settings_new`, `arrow_back`, `arrow_forward`, `expand_more`, `expand_less`, `chevron_right`, `notifications`, `notifications_off`, `record_voice_over`, `camera`, `photo`, `palette`, `brush`, `undo`, `redo`, `content_copy`
size	number	44	Width and height of the button in pixels. Both dimensions are equal.
toggle	boolean	false	When `true` the button latches on each click, toggling `.state` between `true` and `false`. When `false` (default) the button fires once per click and does not latch.
state	boolean	false	Initial toggle state. Only meaningful when `toggle: true`.
iconSize	number	auto	Icon font size in pixels. Defaults to `round(size × 0.58)`.
x, y	number	0, 0	Canvas position of the top-left corner.
label	string	''	Text caption drawn inside the button below the icon.
onClick	function	null	`onClick({buttonState, label}[, control])` — called on release. `buttonState` is `true` on press, `false` on release; for momentary buttons always `false`.
disabled	boolean	false	Suppresses all interaction and draws a disabled overlay.
theme	object	{}	Partial theme override. See Themes.

Properties

Property	Description
`.state`	Read/write. Current toggle state (`true`/`false`). Setting programmatically does not fire `onClick`.
`.icon`	Read/write. Change the displayed icon at any time.
`.disabled`	Read/write. Disables or re-enables the button.

Example

editable — changes update the preview

const play = new IconButton({
  x: 20, y: 20,
  icon: 'play_arrow',
  size: 52,
  label: 'PLAY',
  onClick: () => console.log('play'),
});
const stop = new IconButton({
  x: 90, y: 20,
  icon: 'stop',
  size: 52,
  label: 'STOP',
  onClick: () => console.log('stop'),
});
const loop = new IconButton({
  x: 160, y: 20,
  icon: 'loop',
  size: 52,
  toggle: true,
  label: 'LOOP',
  onClick: s => console.log('loop', s),
});

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.

new XYPad(opts)

Options

Option	Type	Default	Description
width	number	160	Panel width in pixels.
height	number	160	Panel height in pixels.
minX / maxX	number	0 / 1	Value range for the horizontal axis.
minY / maxY	number	0 / 1	Value range for the vertical axis.
valueX / valueY	number	center	Current X and Y position within the pad's range. Read or set at any time to get or move the crosshair programmatically.
scaleX	string	'linear'	`'linear'` or `'log'`. Log requires `minX > 0`.
scaleY	string	'linear'	`'linear'` or `'log'`. Log requires `minY > 0`.
crosshairColor	string	theme accent	Color of the crosshair dot and lines.
onChangeX	function	null	`onChangeX(x[, control])` — called with the new X value when only X changes.
onChangeY	function	null	`onChangeY(y[, control])` — called with the new Y value when only Y changes.
onChange	function	null	`onChange({x, y}[, control])` — called when either axis changes.
onRelease	function	null	`onRelease({x, y}[, control])` — called on release.
springBack	boolean	false	When `true`, both axes animate back to their initial values after mouse/touch release.
springDuration	number	1.0	Seconds for the spring animation to complete.

Example

editable — changes update the preview

const pad = new XYPad({
  x: 20, y: 22,
  width: 220, height: 200,
  minX: -1, maxX: 1,
  minY: -1, maxY: 1,
  valueX: 0, valueY: 0,
  label: 'XY',
  crosshairColor: '#ff6600',
  onChange: ({x, y}) => console.log(x, y),
});

Example — spring back to center

editable — changes update the preview

const pad = new XYPad({
  x: 20, y: 22,
  width: 220, height: 200,
  minX: -1, maxX: 1,
  minY: -1, maxY: 1,
  valueX: 0, valueY: 0,
  label: 'XY  (spring)',
  crosshairColor: '#ff6600',
  springBack: true,
  springDuration: 0.6,
  onChange: ({x, y}) => console.log(x, y),
});

GridPad Input

A 2-D grid of cells with five 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; radio allows exactly one cell to be selected at a time — clicking a cell selects it and clears all others, clicking it again deselects it. Optional horizontal and vertical grouping draws a bevel separator every N cells. Double-click the label to reset all cells to their initial values.

new GridPad(opts)

Options

Option	Type	Default	Description
x, y	number	0	Top-left position.
rows	number	4	Number of rows.
cols	number	4	Number of columns.
mode	string	'toggle'	`'toggle'` — click to flip 0/1 · `'percent'` — hold to raise/lower · `'button'` — momentary press · `'colorselect'` — click to cycle through colours · `'radio'` — one cell selected at a time.
options	array	[]	colorselect mode only. Each entry is either a colour string (`'red'`, `'#ff0000'`) or an object `{ color, value }` where `value` is the semantic value returned by `onChange`. When `value` is omitted it defaults to the colour string.
cellSize	number	20	Pixel size of each square cell.
cellGap	number	2	Gap in pixels between cells.
hGroup	number	0	Draw a bevel separator every N columns. 0 disables.
vGroup	number	0	Draw a bevel separator every N rows. 0 disables.
groupGap	number	4	Extra pixels added at each group boundary.
values	array	all 0	Initial 2-D array `[[row][col]]`. For colorselect, pass indices or semantic values — both are accepted. Ignored in button mode.
rate	number	0.02	Percent change per frame while mouse is held (percent mode only).
label	string	''	Label drawn below the grid.
theme	object	{}	Partial theme override. See Themes.
onChange	function	null	`onChange({r, c, value, values, state}[, control])` — called when any cell changes. `r`/`c` are the cell coordinates, `value` is that cell's new value, `values` is the full 2-D grid, and `state` is `'change'` (toggle/percent/colorselect), `'on'` (button press), `'off'` (button release), or `'reset'` (label double-click).
onRelease	function	null	`onRelease({r, c, value, values, state}[, control])` — called on mouse release with the same payload as `onChange`.

Interaction — toggle mode

Action	Effect
Click cell	Flip value between 0 and 1.

Interaction — percent mode

Action	Effect
Hold left click	Raise value toward 1 at `rate` per frame.
Hold right click	Lower value toward 0 at `rate` per frame.
Double-click at 0	Snap to 1.
Double-click at 1	Snap to 0.
Double-click mid-range	Snap to whichever boundary is closer.

Interaction — button mode

Action	Effect
Press cell	Cell highlights; `onChange({r, c, value, values, state:'on'})` fires.
Release	Cell returns to default; `onRelease({r, c, value, values, state:'off'})` fires.

Interaction — colorselect mode

Action	Effect
Left click	Advance to the next colour in `options`, wrapping around.
Right click	Step back to the previous colour.
Double-click label	Reset all cells to their initial colour (index 0 by default).

Interaction — radio mode

Action	Effect
Click an unselected cell	Select it (value → 1) and clear all other cells (value → 0).
Click the selected cell	Deselect it (value → 0); no cell is active.

Public API

Member	Description
`values` (getter)	Returns a deep copy of the 2-D values array. In colorselect mode returns semantic values, not indices.
`getValue(r, c)`	Returns the value at row `r`, column `c`. In colorselect mode returns the semantic value of the current colour.
`setValue(r, c, v)`	Sets the value at `(r, c)`. In toggle mode snapped to 0/1; percent clamped 0–1; colorselect accepts an index integer. In radio mode, setting a cell to 1 automatically clears all other cells first.
`highlightCell(r, c, on)`	Sets the highlight state of cell `(r, c)`. Pass `true` to highlight, `false` to clear. Out-of-range coordinates are silently ignored.
`highlightRow(r, on)`	Sets the highlight state of every cell in row `r`. Pass `true` to highlight the entire row, `false` to clear it.
`highlightCol(c, on)`	Sets the highlight state of every cell in column `c`. Pass `true` to highlight the entire column, `false` to clear it.

Example — toggle mode (step sequencer)

editable — changes update the preview

const seq = new GridPad({
  x: 20, y: 22,
  rows: 4, cols: 4,
  mode: 'toggle',
  cellSize: 20,
  hGroup: 2, vGroup: 2,
  label: 'PATTERN',
  onChange: ({r, c, value, values, state}) => console.log(r, c, value, state),
});

Example — percent mode (velocity matrix)

editable — changes update the preview

const vel = new GridPad({
  x: 20, y: 22,
  rows: 4, cols: 4,
  mode: 'percent',
  cellSize: 20,
  hGroup: 2, vGroup: 2,
  label: 'VELOCITY',
  onChange: ({r, c, value, values, state}) => console.log(r, c, value, state),
});

Example — colorselect mode

editable — changes update the preview

const seq = new GridPad({
  x: 20, y: 22,
  rows: 4, cols: 4,
  mode: 'colorselect',
  cellSize: 20,
  hGroup: 2, vGroup: 2,
  label: 'COLOR',
  options: [
    { color: '#222222', value: 'off'   },
    { color: '#cc3300', value: 'red'   },
    { color: '#0055cc', value: 'blue'  },
    { color: '#22aa44', value: 'green' },
  ],
  onChange: ({r, c, value, values, state}) => console.log(r, c, value, state),
});

Example — radio mode

editable — changes update the preview

const sel = new GridPad({
  x: 20, y: 22,
  rows: 4, cols: 4,
  mode: 'radio',
  cellSize: 20,
  hGroup: 2, vGroup: 2,
  label: 'SELECT',
  onChange: ({r, c, value, values, state}) => console.log(r, c, value, state),
});

Piano Input

An interactive keyboard component that displays chromatic piano keys. Click any key to select a note. Supports highlighting multiple notes for chords or scales. Perfect for music interfaces or note selection.

new PianoPad(opts)

Options

Option	Type	Default	Description
firstNote	string	'C4'	Starting note as a string, e.g., 'C4', 'G#3', 'Eb2'. Uses standard music notation.
noteCount	number	25	Number of chromatic notes to display. 25 notes spans two octaves + one note (C4 to C6).
highlightedNotes	string[]	[]	Array of note strings to highlight visually (e.g., ['C4', 'E4', 'G4'] for a C major chord).
width	number	500	Keyboard width in pixels.
height	number	120	Keyboard height in pixels.
onChange	function	null	`onChange({note, midi, octave, state}[, control])` — called when a key's state changes. `note` is the note string (e.g., 'C#4'), `midi` is the MIDI number (0-127), `octave` is the octave number, `state` is 'on' (pressed), 'off' (released), or 'highlight' (hovered).
onRelease	function	null	`onRelease({note, midi, octave, state}[, control])` — called when the mouse is released from a pressed key. `state` is always 'off'.

Interaction

Hover over keys to see a subtle tint — fires onChange with state: 'highlight'
Mouse down on a key to press it — fires onChange with state: 'on'
Mouse release — fires onChange with state: 'off' and also onRelease
Highlighted keys show in the accent color to indicate chords or scales

Examples

Basic Piano

Simple keyboard with default settings:

const piano = new PianoPad({
  x: 20, y: 20,
  width: 340, height: 110,
  firstNote: 'C4',
  noteCount: 25,
  onChange: (d) => console.log(d.note, 'state:', d.state)
});

Piano with Chord

Highlight notes to show chords or scales:

const piano = new PianoPad({
  x: 20, y: 20,
  width: 340, height: 110,
  firstNote: 'C3',
  noteCount: 25,
  highlightedNotes: ['C3', 'E3', 'G3'], // C major
  onChange: (d) => console.log(d.note, d.state),
  onRelease: (d) => console.log('Released:', d.note)
});

Buttons

IconButton Input

Options

Properties

Example

XYPad Input

Options

Example

Example — spring back to center

GridPad Input

Options

Interaction — toggle mode

Interaction — percent mode

Interaction — button mode

Interaction — colorselect mode

Interaction — radio mode

Public API

Example — toggle mode (step sequencer)

Example — percent mode (velocity matrix)

Example — colorselect mode

Example — radio mode

Piano Input

Options

Interaction

Examples

Basic Piano

Piano with Chord