JavaScript API

Polypad API Docs

Setup

Our JavaScript API allows you to add interactive Polypad canvases to any website. You simply need to include our JS source file, create a parent element for Polypad, and then call Polypad.create():

<script src="https://polypad.amplify.com/api/latest/polypad.js?lang=en&apiKey=test"></script>
<div id="polypad" style="width: 800px; height: 500px;"></div>
<script>Polypad.create(document.querySelector('#polypad'))</script>

Polypad requires Custom Web Components and the Web Animations API. If you want to use browsers that don't support these APIs, you have to include a polyfill.

Our goal is to support the latest version of Chrome, Firefox, Opera and Edge on all mobile and desktop devices.

Polypad is available in many different languages. The lang query parameter is optional, and can be en, ar, cn, de, es, et, fa, fr, he, hi, hr, hu, id, it, ja, ko, nl, pl, pt, ro, ru, sv, th, tr, uk or vi.

Note: the polypad.js script needs to be included in the <body>, not the <head> of your HTML document.

JSON Schema

Every Polypad canvas consists of a collection of tiles and strokes. The state of a Polypad can be serialised as JSON, with the following schema:

interface TileData {
  name: string,       // The tile type (since 'type' is a reserved field in many databases)
  x?: number,         // X-position
  y?: number,         // Y-position
  rot?: number,       // Rotation (in degrees)
  color?: string;     // HEX colour (e.g. "#ff0044")
  isFlipped?: boolean;
  status?: 'locked'|'fixed'|'hidden';
  altText?: string;
  hideHandles?: boolean;
  layer?: 'front'|'normal'|'back'
  labels?: 'fraction'|'percentage'|'decimal'|'hidden';
  cables?: {fromPort?: string, toPort?: string, toTileId: string}[];
  // Many other tile-specific options, as described in tiles.md
}

interface StrokeData {
  points: string;      // SVG path, or geometric expression
  color?: string;      // HEX colour
  brush: 'pen'|'marker'|'highlighter'
}

interface PolypadOptions {
  toolbar?: string;     // Comma-separated list of toolbar icons to show
  settings?: string;    // Comma-separated list of settings bar icons to show
  sidebar?: string;     // Comma-separated list of sidebar sections to show
  actionbar?: string;   // Comma-separated list of actionbar items to show

  grid?: 'none'|'square2-grid'|'square-dots'|'square-grid'|'tri-dots'|'tri-grid'|'tri2-dots'|'tri2-grid';
  background?: string;

  canvas?: 'infinite'|'notebook'|'fixed';
  canvasX?: number;         // Canvas width (for fixed and notebook view)
  canvasY?: number;         // Canvas height (for fixed view)

  altColors?: boolean;      // Alternate colour scheme for polygons and number bars
  mergeTiles?: boolean;     // Merge number cards or prime factor circles when hovering
  tileWeights?: string;     // Used for balance scales
  algebraXSize?: number;
  algebraYSize?: number;

  noCopyPaste?: boolean;
  noUndoRedo?: boolean;
  noPinchPan?: boolean;
  largeUI?: boolean;
  noDeleting?: boolean;
  noAudio?: boolean;        // Disable sound effects
  noMusic?: boolean;        // Disable sonification tools
  noRotating?: boolean;
  noSnapping?: boolean;
  highContrast?: boolean;
}

interface PolypadData {
  title?: string;
  version?: number;
  options?: PolypadOptions;
  tiles?: Record<string, TileData>;
  strokes?: Record<string, StrokeData>;
}

By default, the maximum length of the tiles and strokes array is 2000. With more items on the same page, you might see performance issues on some devices.

Methods

The Polypad.create() function takes an options argument with many ways to customise Polypad:

interface Polypad {
  create: (options: {
    sidebarTiles?: boolean;     // Whether to show the tiles sidebar
    sidebarSettings?: boolean;  // Whether to show the settings sidebar
    toolbar?: boolean;          // Whether to show the toolbar
    actionbar?: boolean;        // Whether to show the actionbar
    settings?: boolean;         // Whether to show the settings bar
    exportToCL?: boolean;       // Enable value exporting from drop zones
    canvasMargin?: number;      // The margin around fixed size canvases (default 40px)
   
    initiallyClosedSidebar?: boolean;  // Sidebar starts out closed
    lightUI?: boolean;                 // Light colour scheme
    fonts?: [string, string, string];  // Font for [title, body, kids] text
    focusColor?: string;               // Hex colour for focus outlines

    initial?: PolypadData;      // Initial data to show
    resetState?: PolypadData;   // Data to load when users click the "reset" button

    // Allow over-riding default tile props (e.g. for dropzones)
    defaultProps?: Record<string, TileProps>;

    // Override the default theme colours 'red', 'blue', 'green', ...
    themeColours?: Record<string, string>;

    // Provide a way to upload image files: you need to upload the file object to a storage
    // backend and return a promise that resolves with the URL of the uploaded file.
    imageUpload?: (file: File) => Promise<string>;

    // For passing custom button triggers to the Actions Sidebar
    getAvailableButtons?: () => ({id: string, label: string})[];
    subscribeToButtonClick?: (id: string, callback: () => void) => void;
    unsubscribeFromButtonClick?: (id: string) => void;
  }) => PolypadInstance;

  // Extract all exported values from a Polypad data instance.
  getExports: (data: PolypadData) => Record<string, {type: string, value: unknown}|undefined>;

  // Get a static image corresponding to a Polypad data object.
  toImage: (data: PolypadData, type?: 'png'|'svg'|'jpg', width?: number, height?: number) => string;

  // Translates a textbox, equation and image URL instances in a Polypad data object. This function
  // modifies the first argument, and uses the second argument to generate translations.
  translate: (data: PolypadData, translate: (value: string, type: 'html'|'url'|'expr') => string) => string;
}

Polypad.create() then returns a PolypadInstance object with additional methods for manipulating the canvas. Please note that most of these methods don't type-check their input arguments. If you pass in incorrect data, the behaviour is undefined.

interface PolypadInstance {
  // Bind or unbind event listeners. See below for all supported events.
  on: (event: string, callback: (e: unknown) => void) => void;
  off: (event: string, callback: (e: unknown) => void) => void;

  // Serialize or un-serialize a polypad state from JSON data. See above for types.
  serialize: (maxTiles?: number, maxStrokes?: number, maxStrokeLength?: number) => PolypadData;
  unSerialize: (data: PolypadData) => void;

  // Create an image of a given size. This asynchronous function returns a Data URI string.
  image: (width: number, height: number, type?: 'png'|'jpg'|'svg') => Promise<string>;

  // Add, update or delete a tile or stroke. .add() returns the ID of the new item. Note that
  // you cannot update strokes, or update the 'name' property of a tile once created.
  add: (data: TileData|StrokeData, undoable?: boolean) => string;
  update: (id: string, properties: Partial<TileData>, undoable?: boolean) => void;
  delete: (ids: string[], undoable?: boolean) => void;

  // Paste new tile data. Unlilke the "add" function, this de-dupes any tile IDs, dynamic geometry
  // keys and connection cables, so that the same data can be pasted multiple times.
  paste: (data: Record<string, TileData>) => void;

  // Get the current user selection, or programmatically select multiple existing tiles.
  getSelection: () => string[];
  select: (...tileIds: string[]) => void;

  // Undo or redo the latest changes to the canvas.
  undo: () => void;
  redo: () => void;

  // Set the background grid or display options. See the `options` event for more details.
  setOptions: (e: Partial<PolypadOptions>) => void;

  // Switch the currently enabled tool
  setTool: (tool: 'move'|'pen'|'eraser'|'text'|'pan'|'geo', toolOptions?: 'line'|'circle'|'rect'|'angle'|'pen'|'ruler'|'marker'|'highlighter'|'text'|'equation') => void;

  // Clear all tiles on the current canvas. Unline .unSerialize({}), this action can be undone.
  clear: () => void;

  // Get or update the visible viewport of the canvas, or reset it to its initia position.
  getViewport: () => {x: number; y: number; zoom: number};
  setViewport: (x: number, y: number, zoom: number) => void;
  resetViewport: () => void;

  // Translate between the browser coordinate system and Polypad coordinate
  // system by passing an x and y value from Polypad.
  getCoordinates: (x: number, y: number) => {x: number, y: number};

  // Call this function to manually trigger a resize of the Polypad container. We are already
  // using window.resize() and the ResizeObserver API (if available in the Browser).
  resize: () => void;

  // Get all exported values from drop zones
  getExports: () => Record<string, {type: string, value: unknown}|undefined>;

  // Show a floating hand gesture that animates either clicking on a DOM element (no slide)
  // or dragging a DOM element by a certain distance (with slide). The gesture disappears as
  // soon as the target is interacted with.
  showGesture: (selector: string, slide?: {x: number, y: number}) => void;
  
  // Enable keyboard and accessibility shortcuts. See below for details
  bindKeyboardEvents: (keys?: KeyboardShortcuts) => void;
  
  // Remove and clean up this Polypad instance. This action is irreversible, and any further
  // interaction with the instance class may throw undefined Errors.
  destroy(): void;

  // Expand, collapase or toggle the sidebar on the left. With no arguments, the current state
  // is flipped, or you can explicitly specify and expanded or collapsed state.
  toggleSidebar: (expanded?: boolean) => void;

  // Add a custom button to the toolbar or sidebar. You can provide either an HTML string or a
  // DOM Element, and the method returns the new <button> DOM element.
  addCustomButton: (target: 'toolbar'|'settings', body: string|Element = '') => Element
}

Keyboard Events

Using the .bindKeyboardEvents() method, you can enable a large number of built-in keyboard shortcuts. You can always also use the META/CMD key instead of CTRL. Events are bound just to the Polypad instance, and won't be triggered unless Polypad is focussed. Events always include:

Press SPACE or ENTER to "click" the currently focussed button (for accessibility).
CTRL+Z to undo (or redo if SHIFT is also pressed) and CTRL+Y to redo.
BACKSPACE, CLEAR or DELETE to delete all currently selected tiles.
C to create a copy of all currently selected tiles.
CTRL+A to select all tiles.
Default browser CUT, COPY and PASTE events (e.g. using CTRL+C).
Hold SPACE to temporarily switch to the pan tool.
R to rotate the current selection (reverse rotation of SHIFT is also pressed).
ARROW keys to move the currently selected tiles up, down left or right.

In addition, you can pass a parameter to enable some additional shortcuts when specific letter keys are pressed. To prevent this, pass {} as an argument. If you do not pass an arguments, these defaults will be used:

type ToolShortcut = ['tool', 'move'|'pen'|'eraser'|'text'|'pan'|'geo'|'equation'];
type FocusShortcut = ['focus', 'sidebar'|'toolbar'|'canvas'|'actionbar'];
type KeyboardShortcuts = Record<string, ToolShortcut|FocusShortcut>;

const KEYBOARD_SHORTCUTS: KeyboardShortcuts = {
  v: ['tool', 'move'],
  p: ['tool', 'pen'],
  g: ['tool', 'geo'],
  t: ['tool', 'text'],
  q: ['tool', 'equation'],
  e: ['tool', 'eraser'],
  s: ['focus', 'sidebar'],
  d: ['focus', 'toolbar'],
  f: ['focus', 'canvas'],
  a: ['focus', 'actionbar']
};

UI Customisation

The PolypadData.options object contains properties to customise which UI elements are visible, using comma-separated strings. If this field is empty, all items will be shown. Otherwise, only the selected items will be shown.

Toolbar

Options include move, pen, geo, text, equation, eraser, image, and color.

Settings Bar

Options include fullscreen, grid, customise and download. The undo/redo buttons can be hidden using the .noUndoRedo Polypad option, and the pan/zoom buttons can be hidden using the .noPinchPan option.

Sidebar

Options include geometry, polygons, polyominoes, tangram, penrose, pentagons, solids, measuring, patterns, numbers, number-tiles, number-bars, number-frames, number-cards, number-line, primes, number-dots, number-grid, number-tools, fractions, fraction-bars, fraction-circles, algebra, algebra, balance, axes, sliders, probability, probability, charts, playing-cards, polyhedral-dice, non-trans-dice, applications, logic, chess, clocks and dominoes.

Actionbar

Many options, that are simply the label/tooltip of each item, in lowercase and kebab-case. Examples include copy, delete or split-tiles.

Events

Using the .on() and .off() methods on PolypadInstance, you can bind and unbind many different event listeners. The following events are supported:

`.on('change')`

This event is triggered whenever the state of the Polypad changes because the user has added, updated or deleted a stroke or tile. Note that multiple different tiles can change at once, but the event is only triggered once at the end of a move or rotate action.

Callback Options: Record<string, [TileData|StrokeData|undefined, TileData|StrokeData|undefined]>

The callback options is a map of every added, deleted or modified tile or stroke, keyed by their IDs. Every value is an array of the [pevious, updated] state of the corresponding tile or stroke. For example, added items are of the form [undefined, TileData|StrokeData], deleted items are of the form [TileData|StrokeData, undefined], and modified tiles are of the form [Partial<TileData>, Partial<TileData>] containing just the changed properties. This is useful for maintaining your own undo/redo stacks. Note that strokes cannot be modified – only created or deleted.

`.on('viewport')`

Triggered whenever the position of the visible viewport changes, for example because the user pans or zooms. Note that the viewport is not part of the "state" of a polypad. When calling .unSerialize() or .resetViewport(), we update the viewport so that all tiles and strokes are visible and centered.

Callback Options: {x: number, y: number, zoom: number}

`.on('undo')`, `.on('redo')`

Triggered on undo and redo: both from a user input (e.g. clicking the undo button or CTRL + Z on the keyboard), or programatically (e.g. calling .undo() above), You can call .preventDefault() on the event object to prevent the built-in undo/redo handling, and instead apply changes from a custom stack of changes.

Callback Options: Event

Callback Options: Partial<PolypadOptions>

`.on('selection')`

Triggered whenever the current selection changes.

Callback Options: {tiles: string[]}

`.on('move')`

This event is triggered continuously while users are moving one or more tiles. The Callback argument contains the ID and the current position of all currently selected tiles.

Callback Options: {tiles: {id: string, x: number, y: number}[]}

`.on('export')`

Triggered whenever the value of an exported variable changes, when a new export is added or when an existing export is deleted (undefined).

Callback Options: {[name: string]: {type: string, value: unknown}|undefined}

Polypad Changelog

v5.3.1 (22 November 2024)

Bug Fixes

No longer show a white outline around uploaded images by default.

v5.3.0 (20 November 2024)

New Features

New hand tile for number representations.
New defaultProps option to over-write tile default props in the API.
New multi-line text-input tiles.
New Point geometry tool for creating single Points. Allow users to click twice to draw objects (e.g. lines or circles), rather than requiring click-and-drag.
"Show handles" toggle for function machines
Add labels to unit fraction circles.
Add stroke customisation options for images.
Allow dynamic geometry objects to be layered.
Round fixed-size canvas dimensions to tenths place.
Support for pasting recorder tiles from standalone Polypad. The record toolbar buttons are not available in the API.

Bug Fixes

Significant accessibility UI and markup improvements across Polypad.
Immediately save authoring mode changes when clicking toggles, rather than waiting until you leave authoring mode.
Silence action cards in song tile.
Correctly update color picker when switching between fill and stroke.
Fix some kyboard shortcuts.
Fix scaling issues for custom polygons.
Block authoring mode keyboard shortcut when authoring mode is disabled in the API.
Fix quartiles labels in variable tiles.

v5.2.4 (9 October 2024)

New Features

API stub for external button integration.
Allow users to click twice to cut polygons (rather than click+drag).

Bug Fixes

Clear focus when deleting tiles
Fix issues with variable tiles where "undefined" is cast to 0.
Correctly calculate the "mode" with multiple items with the same largest count.
Fix typing issues with number line start/step input fields.

v.5.2.3 (25 September 2024)

New Features

Variable Tiles that can be used to compute properties of one or more tiles on the canvas.
We no longer show the grey canvas mask in fixed size or notebook mode, if the sidebarSettings option is set to false.
New interactivity option "Cannot copy or delete".
Extra options for Exploding dots (labels and exploding speed).
Improved ability to set initial viewport dimensions.

Bug Fixes

Numerous accessibility improvements related to click and focus events, and tabbing order.
Prevent moving non-editable tiles into Dropzones.
Flatten groups for flash action.
Update selection when splitting number cubes.
Fix issues with exploding dots across multiple cells.
Avoid overlapping multiple tiles with click-to-stick.
Support CTRL for undo and authoring.

v5.2.2 (17 September 2024)

New Features

You can now organise number cubes inside ten frames.

Bug Fixes

Fix a crashing bug caused by certain authoring mode settings.

v5.2.1 (13 September 2024)

New Features

Updated color picker. Set custom stroke colours, weights and styles for many tiles. Set the background colour for images, text boxes and equations.
Set the corner radius for textboxes, equations as well as all Polygon tiles (including non-rectangular polygons).
New styling for dropzones, including a new "hover" mode, and the option to customise the hover color.
Add drop shadows to images and textboxes.
Resize the cells of ten frames.

Bugfixes

Pressing F to focus the canvas now returns focus to the last focussed tile.
You can now longer tab into locked text boxes.
Fix a missing "flip" icon in large UI mode.
Fix issues with line heights in text boxes.
Only display CL exports in authoring mode.
Don't clear the selection when entering or exiting authoring mode.

v5.1.2 (15 August 2024)

Bug fixes

Focus and event handling.

v5.1.1 (6 August 2024)

Bug fixes

Always focus the canvas SVG element when clicking it.

v5.1.0 (1 August 2024)

Breaking changes

The arguments of the .delete() method have changed: the tile/stroke IDs now need to be in an array, rather than multiple separate arguments.

New Features

The .add(), .update() and .delete() methods now all take an optional boolean undoable attribute. If true, the changes will be added to the undo/redo stack and can be reverted by the user. If false (default), the changes will be ignored by change detection and cannot be reverted by th user.
Allow manual adjustment of tile weights for images.
Fixed size layout option for textboxes.
Editable toggle for equation areas.
Allow clicking action buttons when sketch tool is enabled.
New CMD+SHIFT+A shortcut to toggle authoring mode
New "difference" clipping option for polygons.

Bug fixes

Significantly improved cut tool and union/intersection/difference/xor computations of polygons.
Fix transformation and copy+paste bugs with grouped geometry elements. Disable rotating of geometry elements.
Layout triggering and z-index fixes for categorizer tiles.
Better handling of arrow key presses when a generator tile is selected.
Fix disappearing geo tiles when resetting canvas.
Better min/max size bounds for images.

v5.0.9 (24 June 2024)

New Features

Significantly improved keyboard accessibility, including selecting multiple tiles, focussing tile handles, trapping focus in modals, and allowing panning with arrow keys.
Separate "visibility" from the other interactivity "status" options. This is backwards-compatible, and allows hiding/showing tiles with action buttons preserve other interactivity options.
Equality labels for the balance scale.

Bug Fixes

Fix validation errors when copy/paste is disabled.
Fix an issue with resizing very tall or wide images.
Change z-index order of actionbar and toolbar.
Clear the selection before stating a "navigate" action.

v5.0.8 (5 June 2024)

Bug Fixes

Issues when selecting equation tiles with an invalid expression.
Improved stay-in-dropzone behaviour with arrow keys and ejected tiles.
Fix validation with export props and grouped tiles.
Replace Amplify Bynder link URLs.
Allow overflow for popups inside the Polypad component box.

v5.0.7 (24 May 2024)

New Features

Significantly updated dropzone behaviour: you can now click on a dropzone to move your current selection into it (click-to-stick), rather than just drag-n-drop. Authors can also mark tiles to "Stay in Dropzones", in which case they return to their original dropzone if ejected from another one, or dragged elsewhere on the canvas. New tiles made using generators with this property are deleted.
Paste Bynder links as images directly onto the canvas.
Don't show rotate tooltips in Large UI mode.
Ability to use a custom font in Large UI mode.
Disable snapping when moving many tiles at once, for performance.

Bug Fixes

Allow using arrow keys to move tiles out of a dropzone with a layout property set.
Fix partial saving of actionbar visibility configurations.
Fix colours in clock thumbnails.
Prevent ALT+drag to copy, when copy+paste is disabled.
Fix a crash with groups containing invalid/empty dynamic geometry tiles.

v5.0.6 (30 April 2024)

New Features

Allow CL export for bounds from any tile
Added getCoordinates function to translate between browser coordinates and Polypad coordinates.

v5.0.5 (10 April 2024)

New Features

New animation options for area playback (unit, rows and columns).

Bug Fixes

Fix color updating when snapping connecting cubes together.
Trigger "change" event when clicking the reset button.

v5.0.4 (4 April 2024)

New Features

Snap Cubes.
Interpolate variables in text boxes and polygon labels using the ${} syntax.
Increment buttons for number cards.
Support coordinate axes in Categorizer tiles.

Bug Fixes

Fix fatel bug when the colour picker is hidden.
Fix incorrect change event when the drawing a single dot with the pen tool.
Fix resetState option in the API.
Fix light-mode styling in action bar popups.
Hide tutorial links in the actionbar.
Don't expand the toolbar unless the pen tool is selected.
Don't resize the variable slide handle when zooming in/out.

v5.0.1 (27 March 2024)

Bug Fixes

Fix fatal bug when dynamically loading new content into an existing canvas.
Fix bug with thumbnail generation.

v5.0.0 (24 March 2024)

This is a significant update. In addition to the breaking changes below, please note that static assets are now hosted on amplify.com rather than mathigon.org.

Breaking Changes

The customSidebar property has been removed.
Don't scale handles and selection outlines when zooming.
Don't show outlines for tiles in a group.

New Features

Ability to edit the value of tiles on the balance scale directly.
Authoring mode toggle for a large UI, and new drawing tool options (pen and eraser only, or coloured pencils) Advanced validation options for drop zones (match, cover and compare).
Allow the song tile to trigger action buttons.
Sonification for dice and spinners.
Authoring option to make text-boxes non-editable.
New button to graph equations.
Split and merge number frames.
Custom major gridlines for ten frames.
Input field for arbitrary-length number bars.
Set the initial viewport in authoring mode.
Reset polypad button.
Translations into many additional languages.

Bug Fixes

TODO

v4.7.8 (27 November 2023)

New Features

Authoring mode toggle to prevent adding and removing vertices of custom polygons.
New "evaluate" button for equations, that replaces the previous toggle. New UI for how evaluated expressions are displayed, as a full equation. Option to change the output type to decimal, fraction or mixed number.
New "navigate" action for buttons that zooms/pans to a specific area of the canvas.
New "single use" toggle for action buttons.
Support recolouring of individual bars in single-series bar charts.

Bug Fixes

Several text box improvements, including better browser compatibility and requiring just a single click to focus once selected.
Fix undo/redo and pinch/pan buttons not always showing up in authoring mode.
Support keyboard shortcuts when SHIFT or CAPS LOCK is pressed.
Tweaks to the "toggle" action, to hide/show each tile individually.
Various minor bug fixes.

v4.7.7 (8 November 2023)

Bug Fixes

Return 0s from function machines as number cards rather than equations.
Don't remove
elements when reformatting text in textboxes.
Fix issues with number frames on the balance scale.

v4.7.6 (28 October 2023)

Bug Fixes

Ensure that decimal number cards produced by function machines can be converted to fractions.
Fix issues where function machines incorrectly rendered mixed numbers.
Fix issues when moving tiles while a function machine is processing.
Allow audio playing for groups/selections of tiles even if they include some non-playable tiles.
Fix bugs when layering song tiles and categorizer tiles.

v4.7.5 (25 October 2023)

New Features

Function machines that can take many different tiles as input and perform a computation. You can invert linear functions, tabulate the items that pass through them, change the function expression, or hide it entirely.
Number cards now support fractions and mixed numbers as a display style.

v4.7.4 (22 October 2023)

New Features

An "Action button" that can be created in authoring mode, and used to trigger actions like rolling dice, playing music or hiding/showing tiles.
Use the "text label" of polygon tiles as numeric value where possible (e.g. on balance scales).
Option to play musical scales in reverse.

Bug Fixes

Update drop zones to work with grouped tiles.
Fix cutting and folding nets with Rectangle tiles.
Return undefined as a CL export for min/max/range when empty.
Fix music playback for fraction circles and continuous area.
Fix positioning of balance scales on fixed-size canvases.
Fix percussion icons in song tile.

v4.7.2 (28 September 2023)

Breaking Changes

The .pinActionbar() method has been removed. Instead, you can set the pin status of the actionbar in the Polypad options (always, never or custom which retains a toggle for users).

New Features

Updated action bar layout with a single dropdown and multiple accordion sections, as well as improvements when only few actions are selected in authoring mode.
Updated instrument samples.
New "arrow" tile.
Added translations for DE, JA, PL, SV, TH, TR, VI

Bug Fixes

Fix cutting flipped tiles and rectangles. Fix folding rectangles.
Improved polygon label alignment.
Fix selection bug after resizing balance scale.
Fix playing card labels.

v4.7.1 (28 August 2023)

New Features

Set exportToCL: true to allow exporting of drop zone values. This happens using a new dropdown in the tile action bar to define exports using a list of different functions, and the new Polypad.getExports() and instance.getExports() methods and the new instance.on('export') event.
Customisable text labels for polygon tiles (authoring mode).
Border radius for rectangle tiles (authoring mode).
Input fields for rectangle width/height and circle radius (authoring mode).
New instruments and sound samples. The "Song" tile is now called a "Track".
Adaptive cursor icons for pen tools, based on thickness and colour.

Bug Fixes

Fix an issue that caused "cables" between different tiles to disappear when loading a canvas.
Fix undo/redo issues with "colliding" tiles (number cards, prime factor circles, playing cards and number dot arrangements).
Fix saving and moving bugs with geometry utensils (ruler, protractor, compass, set triangle).
Enforce the "tile limit" of drop zones. Any additional tiles will cause an existing tiles to move out of the drop zone.
Only highlight a single dropzone when moving tiles.
Fix an issue with detecting loops in expression dependencies.
Fix an issue with flipping number jump tiles.
Hide the fixed size canvas outline when canvasMargin: 0.
Fix issues with saving number grid colours.
Fix issues with Song tile resizing

v4.6.7 (19 July 2023)

New Features

Alpha and ellipse masking of images
A “percussion” version of the Song tile
Vertical grid lines for the Song tile
Set the starting number for number grids (addition, multiplication, and 100 grid)
Option to disable rotating of individual tiles in authoring mode
Proxy performance improvements

Bug Fixes

Lots of bug fixes related to the categorizer / drop zone tile, including padding for small zones, issues when resizing zones containing tiles, issues with groups inside zones, and support for narrower zones.
Disable double-click-to-roll/flip if the corresponding action bar item is disabled
Fix tabulating multiple grouped coins in other languages
Fix merging grouped number tiles

v4.6.6 (6 July 2023)

New Features

Prefix and suffix options for number line labels

v4.6.3 (25 June 2023)

Bug Fixes

Fix a bug where drop zones (e.g. on the balance scale) were not updated afer some changes (e.g. negating number cards, rolling dice, resizing fractions, or deleting tiles).
Fix a bug where no "change" event was triggered after changing UI options (checkboxes in the sidebar, toolbar and actionbar) in authoring mode.
Ensure that the instrument picker is always positioned within the visible viewport
Increase the limits to resize images
Fix a crashing bug when loading some canvases with tile "arpeggiate" options.
Always load Google web fonts required by Polypad (Source Sans Pro). The Polypad.loadFonts() method is now deprecated.

v4.6.2 (8 June 2023)

Breaking Changes

The .on('options') event has been removed. Instead, option changes now trigger a normal .on('change') event and are added to Polypad's undo/redo stack.

Bug Fixes

Add Polypad option changes (e.g. grid, background or algebra tile sizes) to the undo/redo stack.

v4.6.1 (8 June 2023)

Bug Fixes

Correctly render fraction circles with degrees label.

v4.6.0 (7 June 2023)

Breaking Changes

A new "Authoring Mode" that combines the previous "edit hidden tiles" and "select tiles and tools" modes. The UI "presets" have been removed. Instead, all options are shown in authoring mode, and there are new buttons to (de)select all features. Some actions (layer, interactivity, etc.) are only visible in authoring mode, and drop zones and input fields can only be added and edited in authoring mode.
The "Arpeggiation" music option has been removed for all tiles. Instead, you can now pick from a "Scale" dropdown, including "None" for no arpeggiation.

Bug Fixes

Lots of undo/redo bug fixes (especially for geometry tools and exploding dots).
Trigger change events even if undo/redo is disabled in canvas settings.
Selection bug with hidden/locked tiles when the browser tab re-gains focus.

New Features

New Drop Zones that can be used to create drag-n-drop interactives.
New Einstein Hat monotile.
Degrees label option for fraction circles.
Fraction simplification options for number line labels.
Increment buttons for most number input fields in action bar.
Redesigned instrument picker.
Change the "width" property of number lines to non-integer values.
Input fields to set the x/y position of tiles (available in authoring mode).
Set the horizontal and vertical denominator of Algebra tiles to custom values (e.g. to make x/3).

v4.5.6 (8 May 2023)

Bug Fixes

Don't trigger options change event when calling .unSerialize().

v4.5.4 (31 March 2023)

New Features

Option to display fraction bars and fraction circles without unit fraction subdivisions. Resize fraction bars and fraction circles. Increase maximum denominators from 32 to 64.
New setTool() API method to change the currently enabled tool.
Sonification for continuous function plots and for fraction circles. New "angles" and "area" animations for polygons. New instruments and instrument picker.
New instruments and multi-page instrument picker.
Clickable hyperlinks in text boxes.
Tiles now remember the colour of their back side when flipped.
Customise the width of "notebook" style canvases.
Allow playing/animating grouped tiles.

Bug Fixes

The default aggregation method when tabulating probability tiles is "cumulative".
Correctly shade table header background for coloured backgrounds or in dark mode.
Prevent collisions for non-movable tiles.
Fix infinite line drawing on notebook canvases.
Fix label positioning for perimeter animations.
Additional bug fixes related to grouping, input fields.

v4.5.0 (1 February 2023)

Breaking Changes

The "Evaluate expression" option for the entire canvas has been removed. Instead individual equation tiles now have a toggle to tun on evaluating (which is disabled by default).

New Features

Group and ungroup tiles, and tabulate the sum of groups of dice or the sequence of groups of coins.
Split algebra tiles into fractional tiles, horizontally or vertically.
Improved actionbar UI. The actionbar will now always stay within the visible canvas area. New .pinActionbar() method to customise the actionbar position in the API.
Arrows, decorations and display types (line/ray/segment) for dynamic geometry lines.
Flip and rotate number line jumps.
Custom accessible text for all tiles.
Add option to "Hide handles" for fraction circles.
Add scaling for custom rectangles.

Bug Fixes

Fix a number of undo/redo issues with geometric construction tiles. Fux a bug which caused some constructions to disappear when “merging” points.
Fix some bugs with merging number tiles and splitting number cards. Better support for number cards with very large values or decimal values.
Fix some audio playback bugs that could cause certain steps or animations to be skipped.

v4.4.1 (12 January 2023)

New Features

Editable accessibility text for all tiles.

Bug Fixes

Fix moving and action bar positioning for exploding dots.
Fix angle snapping for fraction circles.
Fix textbook shortcut label.
Fix music tempo bugs.
Update translation strings.

v4.4.0

New Features

Ability to switch between "fixed", "notebook" and "infinite" viewport modes. The infinite version is now truly infinite, and expands dynamically based on the content. A new canvasMargin settings defines the minimum margins around the fixed or notebook canvas.
Ability to set the canvas background colour.

Bug Fixes

Enable all Polypad features by default (rather than just the "common" ones).
Fix a bug with Algebra tile collision testing when negating tiles.
Fix bugs that allowed users to bypass certain disabled features (e.g. panning, deleting tiles, or switching tools).
Don't allow users to scale polygons when set to "Cannot Move".
Collapse the sidebar when dragging tiles onto the canvas, if the canvas size is small.

v4.3.4 (18 November 2022)

Breaking Changes

Removed the fullscreen and download image buttons from the API.

New Featurs

New Piano and Song tiles for creating music.
Ability to load external webfonts using Polypad.loadFonts().
Portuguese translations.

Bug Fixes

Many customisation and light-mode UI bug fixes.

v4.3.2 (8 November 2022)

New Features

Translations for 8 additional languages.
Significantly updated fraction circles, with ability to resize, rename, split and merge.
New resizable circle tile.
Ability to change the colour of individual spinner regions.
Animation and sound effect for random number generators.
The default multiplication symbol is now a dot.

v4.3.1 (5 November 2022)

Bug Fixes

Pointer positions are now constrained to within the visible canvas area, so that users cannot drag tiles outside.

v4.3.0 (2 November 2022)

Breaking Changes

The sidebar property when setting up a new canvas has been replaced by two sidebarTiles and sidebarSettings properties.
The "Customise UI" popup has been replaced by a new tab in the sidebar with all settings for customising the UI and featurs of Polypad.
The getCustomiseOptions method and sidebarTab propetry have been removed.
Updated UI for editing hidden or locked tiles on the canvas.

New Feature

Toggle to enable "high contract mode" for a canvas.

Bug Fixes

Better UI when just a single section of tiles is selected in the sidebar.

v4.2.1 (22 October 2022)

New Features

Many new accessibility labels

Bug Fixes

Fixed some accessibility labels for tiles in the sidebar
Make actions work correctly in non-English versions

v4.2.0 (2 October 2022)

New Features

Sonification! Many types of polygons, number bars and fraction bars now have a play button together with detailed audio configuration and animation tools to represent their value or shape using music. This is useful for accessibility, and students can also create entire songs using Polypad.
3D Number cubes for customisable size, which can be used to learn about place value or to create 3D shapes.
Slider to subdivide number bars into their factors, and the to split them into individual tiles.
New "Clone when moving" interactivity type for tiles, that creates a copy when moving it.
Canadian currency option for coins.
New arrow options for number lines and coordinate axes.
Hold shift key to resize rectangles as squares.
Label option for individual sectors in Prime Factor Circles.

Bug Fixes

Updated Spanish translations.
Scale polygons from their centroid, not their local origin.
Don't show the evaluation result of equations if they are single negative numbers.
Various bug fixes related to undo/redo.
Fix bugs with playing card collisions.

v4.1.0 (18 August 2022)

New Features

The API is not available in Spanish using a separate bundle URL. Please note that the this and future English JS bundles now also include a -en in their file name.
Light mode for a white/grey-coloured user interface (sidebar, toolbar and actionbar).
New input field to specify a scale factor for polygon tiles.
"cm" and "in" labels for the ruler tile. Option to hide all labels for the ruler.

Bug Fixes

Many bug fixes related to multiple Polypad instances on the same page.
Many bug fixes for Safari browsers.

v4.0 (12 July 2022)

This is a significant and backwards-compatibility-breaking change to the Polypad API. We have significantly the internal change tracking and storage modal for Polypad tiles. There are three important differences:

Tiles and strokes are now stored in a map/object keyed by their ID, rather than in an array. This applies to both the serialized Polypad JSON, and the data passed to change events.
The options of a tile are now broken up into multiple, typed properties, rather than a single string. More details about these new properties can be found at https://mathigon.io/polypad/tiles.
The colour property of tiles or strokes has been renamed to color, the order property has been renamed to layer, and the flipped property has been renamed to isFlipped. The hidden, locked and fixed properties have been combined into a single status property.
Some tile names have changed from algebra-tile to algebra and from pentomino to polyomino. The grid tile is no longer supported, and the pentagon tile is now just a normal polygon tile.
Change events are much more granular, returning only the tile properties that have changed, rather than the whole object.

Together, these changes allow us to make very significant performance improvements, and enable a number of upcoming features. We have a migration script that can be used to update any existing, stored Polypad data. The updated data will have a version: 2 property for identification.

Breaking Changes

The structure of the TileData, StrokeData and PolypadData interfaces, .paste() arguments and .on('change') callback arguments have changed. See above for details.
Updated colour scheme for number cards and number tiles, to be more consistent across tile types.
Keyboard events (e.g. CTRL+Z to undo) are now bound just to the Polypad instance, rather than document and won't be triggered unless Polypad is focussed. Losing focus also clears the currentl selection. We have enabled many additional keyboard events that previously were not available in the API. They are now enabled using a new .bindKeyboardEvents() method, rather than a bindKeyboardEvents?: boolean property during setup (which has been removed). You can even customise some of the key bindings.

New Features

Ability to "tabulate" probability tiles (e.g. dice) and show their data in a table.
Ability to resize the "x" and "y" values for algebra tiles, using sliders in the sidebar.
Merge action for number bars.
Split actions for number cards.
Actions to quickly create charts linked to tables.
Degree label while rotating tiles.
Temporarily enable the "pan" tool while holding the spacebar.
New PolypadInstance.destroy() method to clean up and remove a Polypad instance.
New Polypad.toImage() method that converts JSON to PNG, JPG or SVG without having to create a Polypad instance.
New Polypad.getCustomiseOptions() method that returns lists of all available options to customise the UI of Polypad.
New Polypad.translate() method that can be used to update text boxes, equations or image URLs within Polypad.

Bug Fixes

Don't allow students to move, copy or delete question input boxes.
Correctly compute quartiles and median in box plots with decimal data.
Hide action bar for question builder tiles (in student mode).
Fix issues with playing cards and coins in exported SVG files.
Correctly set focus on the Polypad DOM element when clicking the canvas.

v3.6 (13 May 2022)

Fixes

Fix loading error when teacherMode is not enabled.

v3.5 (12 May 2022)

New Features

Coin tiles for USD, EUR and GBP.
Support fraction, percentage and π multiple labels for number lines and coordinate axes.
New random number generator tiles with many different discrete and continuous distributions.
New .paste() utility for Polypad instances. Unlike .add(), this de-dupes any tile IDs, dynamic geometry keys and connection cables, so that the same data can be pasted multiple times.
Width and height labels for number tiles.
New .isTeacher property when setting up a new canvas, which allows users to add editable question fields to the canvas.
New "fill" button for number frames.

Breaking Changes

The size of number-card tiles has been reduced from 75x75 px to 50x50 px, to be more consistent with other tiles and the grid background.

Fixes

Hide question field answers when generating thumbnails.
Many bug fixes with copy+paste (including cables and dynamic geometry tiles).
Improved point ordering for un-sorted line/area chart series.
Center new tiles that are being dragged from the sidebar.
Fix bug with storing the active side of some polyhedral dice.
Reduced API file size!

v3.4 (29 March 2022)

New Features

Ten-sided dice
Sound effects, binary display and metronome input for logic gates.
Keyboard shortcut for selecting all tiles and deleting tiles.
Show radians labels as multiples of π when relevant.

Fixes

Allow hiding the "customise" panel in the settings bar.
Fix the knight moves on the chessboard.
Correctly plot tabular data with numbers containing units or ,s.
Keep focus on pasted tiles.
Fix clicking on colour picker RGB fields.
Don't preload sound effects.
Fix copy+paste for dynamic geometry tiles.
Fix action bar positioning for dynamic geometry tiles.
Fix keyboard shortcuts for toolbar buttons.

v3.3 (24 February 2022)

Breaking Changes

The .pngImage() method has been renamed to .image() and accepts and additional type argument that can be PNG, JPG or SVG. PNG exports now have a transparent background, rather than white.
Reorganised "polygons" section in the sidebar, with new tools. Hide 10 and 12-sided regular polygons (these can be created manually using the new generic "regular polygon" tile).

New Features

New "rectangle" and "regular polygon" tiles that can be customised.
New gemetry tool for drawing angles.
Ability to add labels to dynamic geometry elements (including their current value)
Export canvas as JPG or SVG, in addition to PNG.

Fixes

Lots of dynamic geometry fixes when deleting, snapping, or undo/redoing.
Hide "flip" button for symmetric polygons that are not rotated.

v3.2 (17 February 2022)

Breaking Changes

The "grid" and "settings" panels in the settings bar have changed significantly – see below.
Tile weights for the balance scale components are now stored in .options.tileWeights rather than the options strings for each individual balance scale. This used to cause various bugs with multiple balance scales on the same canvas.

New Features

New panel to customise the UI of Polypad and select which features are available. Some options from the old settings panel have moved into the "grid" selection panel (e.g. editing hidden tiles or resetting the viewport).
New mode for editing locked or hidden tiles.
Reset the Polypad viewport when exiting fullscreen mode.
New geometry tool for drawing rectangles.
Support fraction bar denominators up to 32.
New .showGesture() method to help with building onboarding flows.

Fixes

Fix loading of initial Polypad options when instantiating API (e.g. grid).
XSS escaping for content of rich text boxes.
Fix multiple SVG display bugs in Safari (compass, spinners, and number line).
Fix label type when splitting fraction bars into multiple segments.
Hide the actionbar when no valid actions are selected.
Improved snapping when moving geometry construction paths.

v3.1 (7 February 2022)

Breaking Changes

Replace the canvas-wide labelType and noLabels options with a tile-specific labels option. You can now have tiles with multiple different label types on the same canvas, and there is a new selector for fraction bars and circles.

Fixes

Fix equation editor tool selection
Fix initial loading of cached options

v3.0 (4 February 2022)

Breaking Changes

Significantly improved options handling, with many additional ways to customise the UI and features of Polypad:
- All options (e.g. grid, noLabels, altColors, mergeTiles and evalEquations) are now grouped under a PolypadData.options object.
- New toolbar, settings, sidebar and actionbar options can be used to show only a subset of available tiles or buttons in the UI, using a comma-separated string.
- Additional options for noCopyPaste, noUndoRedo, noPinchPan, noDeleting, noAudio, noRotating and noSnapping.
- The .setGrid() method and the .on('grid') event have been removed. You can now just use the .setOptions() method and the .on('options') event.
- The noPanAndZoom property has been removed when setting up Polypad, and is now an option that can be changed dynamically, like the ones above.
New Action Bar that floats under your current selection of tiles or can be pinned to the bottom. This can be used to customise properties of the tile, or apply actions.

New Features

Logic gate tiles, including switches, flip-flops and light bulbs, for learning computer science.
Significantly improved snapping and drawing logic, including snapping to intersections or paths generated using the ruler or protractor utensils. The Stroke.points property can now be both an SVG path string or a geometric expression like segment(point(1,1),point(2,2)).
Inches units for ruler, updated labels for ruler and protractor.
Advanced option to hide the "handles" for different tiles (TileData.hideHandles).
The table and coordinate system icons now appear both in the "algebra" and "data science" sections of the sidebar.

Fixes

Fix undo/redo events when adding geo points that snap to existing constructions.
Split number tiles first into rows, then into individual tiles.
Various improvements to the linking system (styling and UX tweaks).
Various performance improvements and reduced JS bundle size.
Updated "copy" icon.

v2.3 (3 January 2022)

Breaking Changes

Changed the order and position of some sidebar items. Coordinate systems and sliders are now in the "Algebra" selection, while the number line is now in the "Numbers" section. The last section has been renamed to "Games and Applications" and contains a number of new features.
Updated "linking" system that now allows the same tile (e.g. table or equation) to be linked to multiple other tiles (e.g. a coordinate system). The link data is now stored as an array in the cables property of TileData, rather than the previous link string. For any existing, saved Polypad canvases, link: 'abc' needs to be converted to cables: [{toTileId: 'abc'}].

New Features

Create scatter plots that can be created by linkin a table to a coordinate system.
New chessboard and chess pieces tiles, including move hints.
New "ten-frame" tile and two-sided counters.
New number line multiples jumps tile.
New resize handle for the balance scale plates.
Sound effects when applying certain actions (e.g. rolling a die)
Double-click on a function or scatter plot in the coordinate system to change its colour.
Keyboard shortcuts for bold/italic/underlined in rich text boxes.

Fixes

Correctly apply tile transformations when a tile's position is changed by another tile (e.g. the balance scale or bucket of zero).
Fix tile transforms if the x or y coordinates are 0. (This could happen after curring unfolded 3D nets.)
When copying a geometric construction, include all dependency points in the change event data (e.g. the center point when copying a circle).
Improved parsing of equations involving implicit multiplication or mixed numbers.
Add XSS escaping for table tiles.

v2.2 (24 November 2021)

New Features

3D Polyhedra folding
Charts and statistics (row, column, line, area, pie and donut charts, box-and-whiskers plots)
Variable sliders and automatic evaluation of expressions
New compass and set triangle geometry utensils
New clock tile
Transpose action for tables
Sound effects for Polypad actions
Options to disable sound effects and the evaluation of equations

Fixes

Various fixes related to the "Bucket of Zero" tool
Fix issues with hiding and locking some tiles

v2.1 (27 July 2021)

Breaking Changes

Simplified sidebar with renamed sections and grouped tools
Separate toolbar buttons for text boxes and equation editor
New keyboard shortcuts for every tool type (see tooltips), and changed shortcuts for focussing the toolbar and canvas
New option to "negate" number cards, and changed default colours for number cards

New Features

New option to show a second tab in the sidebar
New "number frame", "number dot" and "number grid" tile types
New Polyhedral dice tile
New advanced options to "hide" and "lock the position" of tiles
Algebra tiles for y, y2 and xy
New "join" action to merge multiple polygon tiles
"Expand" and "reduce" options for fraction bars, including denominators up to 1/24
Shuffle, draw and stack options for playing cards
Double-click tiles (e.g. dice and spinners) to randomise or to draw a card
"Flip" action for ruler and protractor

Fixes

Better support for algebra tiles on balance scales, including to solve quadratic equations
Only trigger change events at the end of moving a colour picker slider
Fix numberline resizing when rotated, snap tiles to numberline subdivisions
Hide "exploding dot machine" labels if "hide number labels" option is selected
Fix equation colouring and tile collision bugs
Fix undo/redo issues with "lock" option
Updated icons and resized undo/redo icons
Fix weight of "10" playing card
Fix issues with pressing enter to navigate between table cells

v2.0

Breaking Changes

Updated change and undo/redo handling
- The undo and redo button now only apply to actions by the user, not to tiles added or modified programatically
- The .on('change') event now returns arrays with the previous and updated state of tiles that have changed

New Features

Significantly improved undo/redo and serialisation performance
Selection is preserved for many undo/redo actions

Fixes

Improved change detection when dealing with geometry construction tools, balance scales merging, splitting number cards or prime factor circles, linking equations to coordinate systems, and dragging new tiles from the sidebar onto the canvas
Improved function plotting of implicit equations and containing chained multiplication
Number lines now rotate around their actual center

v1.10

New Features

New tables, dominoes and irregular pentagon tiles
Graph functions by linking equations to coordinate systems
Support for layering and locking tiles using a new advancedOptions setting
New labelType setting for decimal and percentage labels for fraction bars and circles
Number input fields for RGB colour picker, new transparency slider
New Handle to partially shade fraction bars
Improved design for toolbar action buttons
New geometry properties popup in toolbar

Breaking Changes

New "tools" section in the sidebar, including tables, utensils, number lines and coordinate systems
Reduce precision of numbers in stroke strings to 2 decimal places, to reduce size

Fixes

Fix change events for fraction bars, prime factor circles and number tiles
Equation editor bugs
- Super and subscript typing, better spacing
- Serialisation of some expressions
- Correctly layout equations when elements are hidden
Additional sanity checks in case pointer move/end events are triggered before a start event
Prevent right-click events

v1.9

New Features

Rich text support for text boxes
New playing cards component
New mergeTiles settings option to disable merging of number cards
Include settings options(noLabels, altColors, mergeTiles) when serialising and restoring Polypad state
New selection change event

Breaking Changes

Updated sidebar order and new "Tools and Utensils" section
Always switch to the move tool after pasting or uploading an image

Fixes

Fix change events triggered by certain actions (merging/splitting fraction bars and number tiles, locking custom polygons)
Prevent erasing of locked tiles
Fix .toggleSidebar()
Trigger a change event for balance scales if their configuration changes
Trigger a change event when pasting images from clipboard
Prioritise geo points over other points (or grid points) when snapping vertices
Various equation parsing and editing fixes

v1.8

Fixes

Improved support for custom undo/redo stacks

v1.7

Fixes

Fix polypad.getSelection() and locking of tiles
Fix bugs when deleting dots in dot machine
Fix bugs where the dice options value doesn't match the visible face

v1.6

New Features

Return full stroke data in change events (no more max-length). Add options for max number of tiles, strokes and stroke length in .serialize() method.
Add .preventDefault() to undo and redo events.
New options event for the alternate colours and number labels settings, as well as a .setOptions() method to change these values programatically.
New .toggleSidebar() method to expand or collapse the sidebar.
New .addCustomButton() method to create custom toolbar or settings bar buttons.
Paste images directly from the clipboard onto the canvas.

Fixes

Don't delete tiles when clicking backspace inside an input field (e.g. the number line or exploding dots settings fields).
Trigger correct event (added, not changed) when creating text or equation tiles.
Fix bugs when changing the number of exploding dots machine boxes.
Correctly center pasted tiles on the canvas, even when the sidebar is open.
Fix some bugs when pressing escape or shift keys while dragging tiles.
Fix erasing and positioning of fraction circle tiles.
Fix change event data for Abacus tile and equation boxes

v1.5

Breaking Changes

The 'move' event is now triggered continuously, rather than throttled to once every second.

New Features

New noPanAndZoom parameter when setting up a Polypad instance.
Support text selection within equation editor

Fixes

Fixed ID generation and change events for Abakus and Equation tiles
Fixed positioning of tile settings panels (e.g. for numerline)
Trigger change when erasing with a single click (rather than click and drag)
Trigger delete, rather than change, when deleting a text box by making its content ''.
Don't trigger a change event when adding a new Numberline or Axes tiles
Don't close colour or settings popups when clicking on a button inside
Fix motion of geometry utensil handles, range of colour picker sliders
Fix equation editor cursor bugs, nicer styling for Abakus tiles

v1.4

New Features

Abacus tool in sidebar
Equation editor (option for "text box" tool)
Pan tool (under zoom in/out)

Fixes

Improved accessibility for fractions
Trigger "add" not "change" event when dragging tiles from the sidebar
Fixed analytics scripts
Fixed black background in fullscreen mode
Fixed duplicate tile IDs when using copy+paste
Trigger "add" event when drawing a single-dot stroke
Fix colour for Tantrix tiles
Fix cursor bugs in some browsers

Polypad Tile Types

Algebra

Algebra Tile

name: 'algebra'
expr: string – Usually 'x^2', 'x', '1' or their negatives.
splitH: number
splitV: number

Coordinate Axes

name: 'axes'
xMin: number
xMax: number
yMin: number
yMax: number
xStep: string – Pattern: /^[-–]?[0-9,./]*[kmbtq]?[π%]?$/.
yStep: string – Pattern: /^[-–]?[0-9,./]*[kmbtq]?[π%]?$/.
arrows: 'both' | 'none' | 'positive'

Balance

name: 'balance'
level: -1 | 0 | 1
size: number – A number between 120 and 800.

Function Machine Tile

name: 'function-machine'
expr: string – Max length: 50.
height: number – Optional.
hideExpression: boolean – Optional.
invert: boolean – Optional.

Logarithm Bar

name: 'log-bar'
value: number

Slider Tile

name: 'slider'
variable: string – Pattern: /^\w+$/.
min: number
max: number
stepN: number
playback: 'bounce' | 'loop' | 'once'
duration: number
value: number

Algebra Token

name: 'token'
shape: string – Can be 'circle', 'square', 'cross', 'weight', 'star' or 'heart'

Applications

Chess Board Tile

name: 'chess-board'
highlight: 'danger' | 'moves' | 'off' – Optional.

Chess Piece Tile

name: 'chess-piece'
piece: 'b' | 'k' | 'n' | 'p' | 'q' | 'r'
dark: boolean – Optional.

Clock

name: 'clock'
clock: 'free' | 'geared' | 'live'
showSeconds: boolean – Optional.
ms: number – For geared clock.
h: number – For free clock.
m: number – For free clock.
s: number – For free clock.

Currency Tile

name: 'currency'
value: 1 | 10 | 100 | 2 | 20 | 200 | 25 | 5 | 50 – In cents.
currency: 'CAD' | 'EUR' | 'GBP' | 'USD'

Logic Gate

name: 'logic-gate'
gate: 'and' | 'buffer' | 'd' | 'jk' | 'nand' | 'nor' | 'not' | 'or' | 'sr' | 't' | 'xnor' | 'xor'

Logic Speaker

name: 'logic-speaker'

Logic Metronome

name: 'logic-metronome'
bpm: number
running: boolean – Optional.

Button Tile

name: 'logic-button'
state: boolean – Optional.

Toggle Switch Tile

name: 'logic-switch'
state: boolean – Optional.

Bulb Tile

name: 'logic-bulb'

Logic Display

name: 'logic-display'

Piano

name: 'piano'
width: number – Number of visible white keys.
startNote: number – Leftmost white key. Optional.

Song

name: 'song'
width: number
height: number – Number of tracks, usually between 6 and 10.
loops: number – Optional.
startNote: number – Semitones between the bottom node and middle C. Optional.
playbackType: 'sequence' | 'timeline' – Optional.
colSize: number – Optional.
rowSize: number – Optional.
barLength: number – Optional.
showGrid: boolean – Optional.

Fractions

Fraction Bar

name: 'fraction-bar'
denominator: number
count: number – Numerator of the fraction.
active: number – Number of highlighted units. Optional.
combine: boolean – Optional.
size: number – Optional.
showUnitLabel: boolean – This prop was added to prevent backwards-compatibility issues when we added labels to unit Fraction circles, that didn't previously exist. Optional.

Fraction Circle

name: 'fraction-circle'
denominator: number
count: number – Numerator of the fraction.
active: number – Number of highlighted units. Optional.
combine: boolean – Optional.
size: number – Optional.
showUnitLabel: boolean – This prop was added to prevent backwards-compatibility issues when we added labels to unit Fraction circles, that didn't previously exist. Optional.

Geometry

Aperiodic Hat Tile

name: 'aperiodic-hat'
a: number – The two side lengths in the construction Tile(a,b)
b: number

Arrow Tile

name: 'arrow'
width: number
minLength: number – Optional.
maxLength: number – Optional.
round: number – Optional.

Circle Tile

name: 'circle'
radius: number
textLabel: string – Max length: 25. Optional.
textLabelFontSize: number – Optional.
textLabelRotate: boolean – Optional.

Custom Polygon Tile

name: 'custom-polygon'
shape: string – Max length: 10000.
scale: number – Optional.
cornerRadius: number – Optional.
vertexCountLocked: boolean – Optional.
textLabel: string – Max length: 25. Optional.
textLabelFontSize: number – Optional.
textLabelRotate: boolean – Optional.

Egg Tangram

name: 'egg'
index: number – An integer from 0 to 8.

Fractal Tile

name: 'fractal'
index: number – An integer from 0 to 4.

Garden Tile

name: 'garden'
index: number – An integer from 0 to 7.

Kolam Tile

name: 'kolam'
index: number – An integer from 0 to 5.

Penrose

name: 'penrose'
index: number – An integer from 0 to 1.

Polyomino

name: 'polyomino'
index: number – An integer from 0 to 11 for pentominoes, and from 12 to 16 for tetroninoes.
textLabel: string – Max length: 25. Optional.
textLabelFontSize: number – Optional.
textLabelRotate: boolean – Optional.

Polygon Tile

name: 'polygon'
shape: string – Either a named polygon ('equ-triangle', 'square', 'reg-pentagon', 'reg-hexagon', 'reg-heptagon', 'reg-octagon', 'reg-decagon', 'reg-dodecagon', 'rectangle', 'trapezium', 'rhombus', 'right-triangle', 'rhombus-2', 'chevron', 'right-triangle-2', 'kite' or 'dart'), or a string of vertex coordinates like 0 0,1 0,1 1,0 1. Max length: 10000.
cornerRadius: number – Optional.
scale: number – Optional.
textLabel: string – Max length: 25. Optional.
textLabelFontSize: number – Optional.
textLabelRotate: boolean – Optional.

Polyhedron Tile

name: 'polyhedron'
net: string – Either a predefined shape (Tetrahedron, Cube, Octahedron, Dodecahedron, Icosahedron, Prism, Pyramid) or a JSON net. Max length: 10000.
hinge: number – Number from 0 (open) to 1 (closed). Optional.
rotation: string – Pattern: /^([0-9.-]+,?){3}$/.

Rectangle Tile

name: 'rectangle'
width: number
height: number
cornerRadius: number – Optional.
scale: number – Optional.
textLabel: string – Max length: 25. Optional.
textLabelFontSize: number – Optional.
textLabelRotate: boolean – Optional.

Regular Polygon Tile

name: 'reg-polygon'
sides: number
cornerRadius: number – Optional.
scale: number – Optional.
textLabel: string – Max length: 25. Optional.
textLabelFontSize: number – Optional.
textLabelRotate: boolean – Optional.

Tangram

name: 'tangram'
index: number – An integer from 0 to 6.

Tantrix Tile

name: 'tantrix'
index: number – An integer from 0 to 13.

Ruler

name: 'ruler'
width: number
isFixed: boolean – Optional.

Protractor

name: 'protractor'
width: number

Set Triangle

name: 'set-triangle'
width: number

Compass

name: 'compass'
width: number

Numbers

Abacus

name: 'abacus'
positions: string – Positions of the beads. Optional. Pattern: /^[0-9.,-]+$/. Max length: 50.

Zero Bucket

name: 'bucket'

Decimal Grid

name: 'decimal-grid'
width: number – Optional.
height: number – Optional.
base: number – Optional.

Dot Machine

name: 'dot-machine'
base: number – Number base used by the machine.
boxes: number – Number of boxes in the machine.
speed: 'fast' | 'medium' | 'slow'

Dot Tile

name: 'dot'
value: -1 | 1
textLabel: string – Max length: 25. Optional.
textLabelFontSize: number – Optional.
textLabelRotate: boolean – Optional.

Hand Tile

name: 'hand-tile'
value: number
width: number

Number Bar

name: 'number-bar'
value: number
denominator: number – Number of subdivisions. Optional.

Number Card

name: 'number-card'
value: number
valueStr: string – Max length: 25. Optional.

Number Cube

name: 'number-cube'
vx: number
vy: number
vz: number

Number Dot

name: 'number-dot'
factors: string – A factor representation of the number. For example, 12 could be represented as '2-2-3'. Pattern: /^[0-9-]+$/.

Number Frame Tile

name: 'number-frame'
value: number – Positive integer.

Number Grid Tile

name: 'number-grid'
kind: 'addition' | 'multiplication' | 'number'
cols: number
rows: number
colors: string – Max length: 5000. Optional.
hStart: number
vStart: number

Jump Tile

name: 'multi-jump'
jumpSize: number
jumps: number
single: boolean – Optional.

Number Line

name: 'number-line'
start: string – Pattern: /^[-–]?[0-9,./]*[kmbtq]?[π%]?$/.
step: string – Pattern: /^[-–]?[0-9,./]*[kmbtq]?[π%]?$/.
width: number
size: number
minor: number
arrows: 'both' | 'none' | 'positive'
simplify: 'all' | 'integers' | 'none'
prefix: string – Max length: 10. Optional.
suffix: string – Max length: 10. Optional.

Number Tile

name: 'number-tile'
width: number
value: number

Prime Disk

name: 'prime-disk'
value: number – Positive integer.

Snap Cube Tile

name: 'snap-cube'
value: number – Positive integer.
colors: string – Comma-separated hex colours of the cubes. Optional. Max length: 1000.

Ten Frame Tile

name: 'ten-frame'
cols: number
rows: number
rowMajor: number – Major grid-line increments for rows. Optional.
colMajor: number – Major grid-line increments for columns. Optional.
boxSize: number
fillColor: string – Pattern: /^#[\w]{3,8}$/.

Ten Frame Counter

name: 'ten-frame-counter'
value: -1 | 1

Others

Action Card

name: 'action-card'
actionId: string – Max length: 50.
duration: number – Optional.
userLabel: string – Max length: 50.
width: number
singleUse: boolean – Optional.
alternateZoom: boolean – Optional.
useIcon: boolean – Optional.
textLabel: string – Max length: 25. Optional.
textLabelFontSize: number – Optional.
textLabelRotate: boolean – Optional.

Categorizer Tile

name: 'categorizer'
width: number
height: number
fillColor: string – Pattern: /^#[\w]{3,8}$/.
focusColor: string – Pattern: /^#[\w]{3,8}$/.
layout: 'center' | 'flow' | 'none'
allowed: string – Max length: 100. Optional.
max: number – Optional.
padding: number – Optional.
tolerance: number – Optional.
validation: 'compare' | 'cover' | 'match' | 'none'
showMark: boolean – Optional.
storedSolution: string – Max length: 10000. Optional.
correct: boolean – Optional.
compareType: string – Max length: 100. Optional.
compareOperator: '<' | '<=' | '=' | '>' | '>=' – Optional.
compareValue: number – Optional.
useTranslations: boolean – Optional.
autoCheck: boolean – Optional.
cornerRadius: number – Optional.

Computed Card

name: 'computed-card'
fn: 'abs' | 'angleSum' | 'area' | 'circumference' | 'count' | 'deg' | 'diameter' | 'difference' | 'eq' | 'gt' | 'gte' | 'length' | 'lt' | 'lte' | 'max' | 'mean' | 'median' | 'min' | 'mode' | 'neq' | 'perimeter' | 'prod' | 'q1' | 'q2' | 'rad' | 'radius' | 'range' | 'ratio' | 'std' | 'sum' | 'value' | 'var'
value: number – Optional.
variable: string – Pattern: /^\w+$/. Optional.

Equation Tile

name: 'equation'
expr: string – An ASCII-Math expressions. Max length: 1000.
evaluate: boolean – Optional.
fontSize: number – Optional.
fillColor: string – Pattern: /^#[\w]{3,8}$/. Optional.
cornerRadius: number – Optional.
editable: boolean – Optional.

Geo Tile

name: 'geo'
key: string – All dynamic geometry objects have a unique key prefixed with '_x'. Pattern: /^_x[0-9]+$/.
expr: string – A geometric expression like point(10,20) or segment(_x1,_x2). Max length: 100.
label: string – Max length: 100. Optional.
arrows: 'both' | 'end' | 'start' – Optional.
marks: 'arrow' | 'arrow2' | 'bar' | 'bar2' – Optional.

Group

name: 'group'
children: string – Max length: 1000.

Image Tile

name: 'image'
href: string – The URL of the image, which should be returned by the imageUpload() config function. Max length: 100.
width: number – Optional.
mask: string – Max length: 5000. Optional.
aiGen: boolean – Optional.
dropShadow: boolean – Optional.

Player Tile

name: 'recorder'
micURL: string – Max length: 100. Optional.
timeline: string – Max length: 500000.
duration: number
showCursor: boolean – Optional.
playMic: boolean – Optional.

Blank Question Tile

name: 'question-blank'
solution: string – Max length: 50. Optional.
submitted: string – Max length: 10000. Optional.
width: number
height: number
placeholder: string – Max length: 100. Optional.
mode: 'question' | 'text'
fillColor: string – Pattern: /^#[\w]{3,8}$/.
fontSize: number – Optional.

Text Tile

name: 'text'
html: string – The rich text HTML of the string. :warning: Remember to do XSS sanitisation before saving this in a DB. Max length: 10000.
fontSize: number – Optional.
width: number – Optional.
fillColor: string – Pattern: /^#[\w]{3,8}$/. Optional.
cornerRadius: number – Optional.
height: number – Optional.
editable: boolean – Optional.
layout: 'auto' | 'fixed' – Optional.
dropShadow: boolean – Optional.

Viewport Tile

name: 'initial-viewport'
width: number
height: number

Probability

Playing Card

name: 'card'
cards: string – :-separated list of 2-letter card names (e.g. 7H or AS). Pattern: /^\w\wf?(:\w\wf?)*$/. Max length: 1000.

Coin

name: 'coin'
value: 0 | 1

Dice

name: 'dice'
value: number – Number from 1 to 6.
faces: string – Pattern: /^[0-9,]+$/. Optional.
playback: 'beats' | 'duration' | 'pitch' | 'subdivisions' – Optional.

Domino Tile

name: 'domino'
a: number
b: number

Polyhedral Dice

name: 'polyhedral-dice'
value: number
faceCount: number
playback: 'beats' | 'duration' | 'pitch' | 'subdivisions' – Optional.

Random Number

name: 'random'
value: number
dist: 'bernoulli' | 'binomial' | 'cauchy' | 'continuous' | 'discrete' | 'exponential' | 'geometric' | 'normal' | 'poisson'
p1: number
p2: number – Optional.

Regular Spinner

name: 'spinner'
sectorCount: number
angle: number
colors: string – Max length: 200. Optional.
playback: 'beats' | 'duration' | 'pitch' | 'subdivisions' – Optional.

Custom Spinner

name: 'custom-spinner'
sectorSizes: string – Pattern: /^[0-9,]+$/. Max length: 100.
angle: number
colors: string – Max length: 200. Optional.
playback: 'beats' | 'duration' | 'pitch' | 'subdivisions' – Optional.

Statistics

Box Whisker Tile

name: 'box-whisker'
kind: 'area' | 'box-whisker' | 'column' | 'donut' | 'line' | 'pie' | 'row' – Optional.
layout: 'grouped' | 'outliers' | 'percentage' | 'stacked' – Optional.
width: number – Optional.
height: number – Optional.
colors: string – Max length: 200. Optional.

Chart Tile

name: 'chart'
kind: 'area' | 'box-whisker' | 'column' | 'donut' | 'line' | 'pie' | 'row' – Optional.
layout: 'grouped' | 'outliers' | 'percentage' | 'stacked' – Optional.
width: number – Optional.
height: number – Optional.
colors: string – Max length: 200. Optional.

Pie Chart Tile

name: 'pie-chart'
kind: 'area' | 'box-whisker' | 'column' | 'donut' | 'line' | 'pie' | 'row' – Optional.
width: number – Optional.
colors: string – Max length: 200. Optional.

Table Tile

name: 'table'
data: string – Max length: 10000.
aggregation: 'computed' | 'cumulative' | 'function' | 'replace' | 'timeseries' – Optional.

Zmień język

Zalogować się

Stwórz nowe konto

Ustawienia konta

Zresetuj hasło

JavaScript API

Polypad API Docs

Setup

JSON Schema

Methods

Keyboard Events

UI Customisation

Toolbar

Settings Bar

Sidebar

Actionbar

Events

.on('change')

.on('viewport')

.on('undo'), .on('redo')

.on('selection')

.on('move')

.on('export')

Polypad Changelog

v5.3.1 (22 November 2024)

Bug Fixes

v5.3.0 (20 November 2024)

New Features

Bug Fixes

v5.2.4 (9 October 2024)

New Features

Bug Fixes

v.5.2.3 (25 September 2024)

New Features

Bug Fixes

v5.2.2 (17 September 2024)

New Features

Bug Fixes

v5.2.1 (13 September 2024)

New Features

Bugfixes

v5.1.2 (15 August 2024)

Bug fixes

v5.1.1 (6 August 2024)

Bug fixes

v5.1.0 (1 August 2024)

Breaking changes

New Features

Bug fixes

v5.0.9 (24 June 2024)

New Features

Bug Fixes

v5.0.8 (5 June 2024)

Bug Fixes

v5.0.7 (24 May 2024)

New Features

Bug Fixes

v5.0.6 (30 April 2024)

New Features

v5.0.5 (10 April 2024)

New Features

Bug Fixes

v5.0.4 (4 April 2024)

New Features

Bug Fixes

v5.0.1 (27 March 2024)

Bug Fixes

v5.0.0 (24 March 2024)

Breaking Changes

New Features

Bug Fixes

v4.7.8 (27 November 2023)

New Features

Bug Fixes

v4.7.7 (8 November 2023)

Bug Fixes

v4.7.6 (28 October 2023)

Bug Fixes

v4.7.5 (25 October 2023)

New Features

`.on('change')`

`.on('viewport')`

`.on('undo')`, `.on('redo')`

`.on('selection')`

`.on('move')`

`.on('export')`