ProControls — Menus Tutorial

Welcome! This tutorial covers the two menu controls in ProControls — the Menu (a full menu bar that can be placed along any edge of the canvas) and the PopupMenu (a floating context menu that appears at a specific position). Each control is explained in four steps, from a single line of code up to real-world usage with submenus and callbacks. Every code block is live and editable — click inside one, make a change, and the preview updates automatically.

First time here? Visit Getting Started for the HTML setup and script tags needed before running these examples in your own project.

Menu PopupMenu

A Menu is a menu bar that runs along one edge of the canvas, just like the application menus you see in desktop software. Items are defined as a simple array of strings. Any item can become a parent with a submenu by replacing the string with an array — the first element is the label and the remaining elements are the submenu entries. Clicking a leaf item fires onChange.

Step 1 Your first Menu

Create a Menu with an items array. By default the menu bar sits along the top edge of the canvas. Click any item in the preview to see it highlighted — items with no submenu are leaf items you can act on.

editable — click menu items in the preview

const menu = new Menu({
  x: 0, y: 0,
  width: 400,
  items: ['File', 'Edit', 'View', 'Help'],
});

Step 2 Choosing an orientation

The orientation option controls which edge the bar sits on and which direction submenus open. Use 'top' or 'bottom' for a horizontal bar, or 'left' or 'right' for a vertical sidebar. The bar automatically snaps to the corresponding edge.

editable — try orientation:'right' or 'bottom'

const menu = new Menu({
  x: 0, y: 0,
  orientation: 'left', // try: 'top', 'bottom', 'left', 'right'
  items: [
    'File',
    ['Edit', 'Undo', 'Redo', 'Cut', 'Copy', 'Paste'],
    'View',
    ['Help', 'About', 'Docs'],
  ],
  onChange: (lbl, path) => console.log(path),
});

Note: orientation:'right' automatically sticks the bar to the right edge of the canvas, and 'bottom' sticks to the bottom — you don't need to calculate the canvas size yourself.

Step 3 Submenus — nest items as arrays

Replace any string in items with an array to create a submenu. The first element of the array becomes the parent label — the remaining elements are the submenu entries. Click a parent item to open its submenu, then click a submenu entry to select it. Submenus can be nested inside any orientation.

editable — click Edit or Help to open submenus

const menu = new Menu({
  x: 0, y: 0,
  width: 400,
  items: [
    'File',
    ['Edit', 'Undo', 'Redo', '---', 'Cut', 'Copy', 'Paste'],
    'View',
    ['Help', 'About ProControls', 'Read the Docs', 'Report a Bug'],
  ],
  onChange: (lbl, path) => console.log(path),
});

Step 4 Reading selections with onChange

The onChange callback fires when the user clicks a leaf item (a non-parent entry). It receives two arguments: label — the text of the clicked item, and path — an array of labels from the root down to the selection. Use path when you need to know which parent menu an item came from. Click items below and watch the console!

editable — click any leaf item and watch the console

const menu = new Menu({
  x: 0, y: 0,
  width: 400,
  items: [
    'File',
    ['Edit', 'Undo', 'Redo', 'Cut', 'Copy', 'Paste'],
    'View',
    ['Help', 'About', 'Docs'],
  ],
  onChange: (label, path) => {
    // label = 'Undo', path = ['Edit', 'Undo']
    console.log('Selected:', label);
    console.log('Full path:', path.join(' → '));
  },
});

Tip: Reassign menu.items at any time to update the menu structure dynamically — useful for toggling checkmarks or enabling/disabling entries. Set menu._layoutDirty = true after reassigning to trigger a redraw.

PopupMenu

Context Menu

A PopupMenu is a floating vertical menu positioned at a specific canvas coordinate — the classic context menu. It accepts exactly the same options as Menu but is pre-configured with orientation: 'popup', so you never need to set it yourself. Submenus automatically flip left or right depending on where the menu sits on the canvas, so they always stay within the visible area.

Step 1 Your first PopupMenu

Create a PopupMenu with x, y, and an items array. It appears immediately as a floating vertical list. Click a parent item to open its submenu, and notice how the submenu arrow and direction automatically adapt to the menu's position.

editable — click items to open submenus

const menu = new PopupMenu({
  x: 20, y: 20,
  items: [
    'File',
    ['Edit', 'Undo', 'Redo', 'Cut', 'Copy', 'Paste'],
    'View',
    ['Help', 'About', 'Docs'],
  ],
  onChange: (lbl, path) => console.log(path),
});

Step 2 Positioning — auto-flip on the right half

Set x and y to place the menu anywhere on the canvas. When the menu sits in the right half of the canvas, submenus automatically open to the left so they don't overflow off-screen — you never need to calculate this yourself. Try moving x to a larger value to see the submenu flip direction.

editable — try x:160 to see submenus flip left

const menu = new PopupMenu({
  x: 20, y: 20,   // try x: 160 — submenus flip to the left
  items: [
    ['Edit', 'Undo', 'Redo', 'Cut', 'Copy', 'Paste'],
    ['View', 'Zoom In', 'Zoom Out', 'Full Screen'],
    ['Help', 'About', 'Docs'],
  ],
  onChange: (lbl, path) => console.log(path),
});

How it works: ProControls checks whether the menu's horizontal centre is in the left or right half of the canvas. If it's in the right half, all submenus open leftward. This matches the behaviour of native OS context menus.

Step 3 Reading selections with onChange

The onChange callback works exactly the same as in Menu — it fires on every leaf item click and receives (label, path). Use path to distinguish items with the same label that appear in different submenus. Click items below!

editable — click a leaf item and watch the console

const menu = new PopupMenu({
  x: 20, y: 20,
  items: [
    'New File',
    ['Open Recent', 'project.p5', 'demo.p5', 'sketch.p5'],
    'Save',
    'Export',
  ],
  onChange: (label, path) => {
    console.log('Selected:', label);
    if (path.length > 1) {
      console.log('Under:', path[0]);
    }
  },
});

Step 4 Context menu pattern — show at mouse position

The most common pattern is to create a PopupMenu at the current mouse position when the user right-clicks. In p5.js you can do this inside mousePressed() by checking mouseButton === RIGHT. Create a fresh menu each time — any previously open menu is automatically replaced.

editable — right-click anywhere in the preview canvas

// Right-click anywhere on the canvas to open the context menu
function mousePressed() {
  if (mouseButton === RIGHT) {
    new PopupMenu({
      x: mouseX, y: mouseY,
      items: [
        'Add Control',
        ['Set Theme', 'Black', 'Stainless', 'White', 'Brushed'],
        'Clear Canvas',
        'Export PNG',
      ],
      onChange: (lbl, path) => console.log('Action:', path.join(' → ')),
    });
    return false; // prevent browser context menu
  }
}

Tip: Returning false from mousePressed in p5.js prevents the browser's own right-click context menu from appearing over your canvas, giving the ProControls menu the whole stage.