Show Non-Colliding Sensors in Matter.js Render

Matter.js allows developers to create trigger zones using sensor bodies that detect collisions without causing physical deflection or bounce. Visualizing these non-colliding trigger areas during development is straightforward using the built-in showSensors debug flag in the Matter.js renderer. This article explains how to configure a body as a sensor, enable the showSensors rendering option, and verify trigger areas visually on the canvas.

Defining a Sensor Body

A sensor in Matter.js is standard rigid body with its isSensor property set to true. This property disables physical collision responses while still generating collision events (collisionStart, collisionActive, and collisionEnd).

const triggerArea = Matter.Bodies.rectangle(400, 300, 200, 100, {
  isSensor: true,
  isStatic: true // Often static so it acts as a stationary trigger zone
});

Matter.Composite.add(engine.world, triggerArea);

Enabling showSensors in the Renderer

To display sensor areas visually, configure the Render instance by setting showSensors to true within its options object.

const render = Matter.Render.create({
  element: document.body,
  engine: engine,
  options: {
    width: 800,
    height: 600,
    wireframes: true, // Recommended for debug flags
    showSensors: true
  }
});

Matter.Render.run(render);

If the renderer is already initialized, update the property directly on the instance:

render.options.showSensors = true;

Display Behavior and Wireframes

When wireframes: true is set alongside showSensors: true, the default Matter.js renderer styles sensor bodies differently from regular dynamic or static bodies, typically using a distinct color or dashed outline to signify that the body allows other objects to pass through.

If wireframes is set to false for a customized look, showSensors may not automatically override custom styling. To ensure visibility while wireframes: false is active, specify fill styling directly on the sensor body:

const triggerArea = Matter.Bodies.rectangle(400, 300, 200, 100, {
  isSensor: true,
  isStatic: true,
  render: {
    fillStyle: 'rgba(0, 255, 0, 0.3)',
    strokeStyle: 'green',
    lineWidth: 1
  }
});

Using showSensors with wireframe rendering provides the fastest and most reliable debug visualization for checking trigger boundaries, alignments, and sensor placements across the canvas.