Buttons

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.

Options

Option	Type	Default	Description
icon	string	'star'	Material Symbols icon name, e.g. 'play_arrow', 'volume_up', 'settings'. Full list at fonts.google.com/icons.
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

---

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

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

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

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.
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(values[, control]) — called with a 2-D copy of values when any cell changes. In colorselect mode the grid contains the semantic value for each cell.
onRelease	function	null	onRelease(values[, control]) — toggle/percent: called with the values array on release. Button mode: called with ({r, c}[, control]) — row and column of the released cell.
onPress(row, col)	function	null	Button mode only — called with the row and column of the pressed cell.

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; onPress(row, col) fires.
Release	Cell returns to default; onRelease({r, c}) 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).

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.

Example — toggle mode (step sequencer)

Example — percent mode (velocity matrix)

Example — colorselect mode

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) });

---