Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.


NPM Package Build Status License

Presentation-quality WebGL math graphing


MathBox is a library for rendering presentation-quality math diagrams in a browser using WebGL. Built on top of Three.js and ShaderGraph it provides a clean API to visualize mathematical relationships and animate them declaratively.

For background, see the article series on



And many more at


You can install MathBox via npm for use with a bundler like Webpack, or include a global MathBox object onto your page by including the library via CDN.

NPM Package

  • Run the following in your project's directory to install MathBox and Three.js via npm:
npm install mathbox three

Import THREE and MathBox (library and stylesheet), along with a controls instance that you'll pass to the MathBox.mathBox constructor:

import "mathbox/mathbox.css"

import * as THREE from "three"
import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js"
import * as MathBox from "mathbox"

Install via CDN

Include the following in your HTML header to load all required libraries and styles:

<!-- Install your choice of three.js version from CDN: -->

<!-- Load a Controls instance, making sure that the version matches the Three.js version above: -->

<!-- Install the latest MathBox, either mathbox.js or mathbos.min.js -->

<!-- Include the MathBox CSS: -->

Basic Usage

Construct a MathBox instance by passing initialization options to the mathBox() constructor:

const options = {
  controls: {
    // Orbit controls, i.e. Euler angles, with gimbal lock
    klass: THREE.OrbitControls
const root = MathBox.mathBox(options);

Note See threestrap for all available options.

To spawn inside a specific element, pass an HTMLElement with the element option:

const element = document.querySelector("#my-thing");

const options = {
  element: element,
  controls: {
    klass: THREE.OrbitControls
const root = MathBox.mathBox(options);

On initialization, mathBox returns a MathBox API object, wrapping the MathBox <root/>. Insert new MathBox nodes into the component tree by calling the method associated with the primitive you'd like to add.

Note See the Primitives doc for a description of all primitives and their properties.

The following code will set up a 3D Cartesian coordinate system with the specified range and scale for its x, y and z axes, and then insert an x and y axis into the scene:

const view = root
    range: [
      [-2, 2],
      [-1, 1],
      [-1, 1],
    scale: [2, 1, 1],
    axis: 1,
    axis: 2,

Use your mouse to click and drag the camera's orientation, and zoom in and out:

2023-01-19 11 32 59

Each primitive call:

  • creates a new element
  • inserts it into the tree
  • returns a version of the API object with its selection focused on the new element.

Calling print() on some selection will print a representation to the console of the selection and any children. For example, view.print() prints the following:

    [-2, 2],
    [-1, 1],
    [-1, 1],
  scale={[2, 1, 1]}
  <axis axis={1} />
  <axis axis={2} />

Select objects using .select() and a CSS-like selector to get a jQuery-like selection:"cartesian > axis");

Next, visit the Quick Start page for a more involved example that builds up an animating, interactive mathematical graph with labeled axes.

Docs & Help

For help, see the following resources:

For more involved questions, or just to say hi, please join us in the MathBox Google Group.

Related Projects

Who's using MathBox?

And the many demos listed on this thread of the MathBox Google group.


MIT License.

MathBox and ShaderGraph (c) Steven Wittens 2013-2023.

Libraries and 3rd party shaders (c) their respective authors.