How to Show Bounding Boxes in Matter.js Render

Yes, you can display bounding boxes using the Matter.js Render module. The engine provides built-in configuration flags in its rendering pipeline designed specifically for debugging collision boundaries and spatial dimensions. This article explains how to enable bounding box visualization through standard render options, dynamically toggle them at runtime, and render custom bounding overlays using Canvas API hooks.

Enabling Bounding Boxes in Render Options

The most direct way to visualize bounding boxes is through the configuration object passed to Matter.Render.create(). By setting showBounds to true within the options object, Matter.js will draw the axis-aligned bounding box (AABB) around every active physics body in the simulation.

const { Engine, Render, Runner, Bodies, Composite } = Matter;

const engine = Engine.create();

const render = Matter.Render.create({
    element: document.body,
    engine: engine,
    options: {
        width: 800,
        height: 600,
        wireframes: false,
        showBounds: true // Enables bounding box rendering
    }
});

Render.run(render);
Runner.run(Runner.create(), engine);

When showBounds is enabled, Matter.js outlines the body.bounds property of each body. This displays the smallest rectangle aligned with the screen axes that completely encloses the shape, which updates in real-time as bodies translate and rotate.

Toggling Bounding Boxes Dynamically

You do not need to recreate the renderer to enable or disable bounding boxes. You can modify the property directly on the existing render instance:

// Enable bounding boxes
render.options.showBounds = true;

// Disable bounding boxes
render.options.showBounds = false;

This is particularly useful when creating debug overlays or user-toggled controls within an application interface.

How Matter.js Computes Bounding Boxes

Each body in Matter.js has an internal bounds property structured with minimum and maximum coordinate vectors:

body.bounds = {
    min: { x: Number, y: Number },
    max: { x: Number, y: Number }
};

These bounds are recalculated automatically whenever a body moves, scales, or rotates. The broadphase collision system uses these bounding boxes to quickly discard pairs of bodies that are too far apart to collide before running more expensive narrowphase collision checks.

Drawing Custom Bounding Boxes

If the default showBounds visual style does not meet your needs—such as requiring custom stroke colors, line widths, or labels—you can draw your own using the afterRender event:

Matter.Events.on(render, 'afterRender', () => {
    const context = render.context;
    const bodies = Composite.allBodies(engine.world);

    context.beginPath();
    context.strokeStyle = 'rgba(255, 0, 0, 0.7)';
    context.lineWidth = 1;

    for (let i = 0; i < bodies.length; i++) {
        const body = bodies[i];
        const min = body.bounds.min;
        const max = body.bounds.max;
        const width = max.x - min.x;
        const height = max.y - min.y;

        context.strokeRect(min.x, min.y, width, height);
    }
});

Using afterRender provides complete control over the visual presentation while still leveraging the accurate, precomputed AABB coordinates provided by Matter.js.