How to Hide Wireframes in Matter.js

Matter.js enables wireframe mode by default to prioritize debugging and performance, but you can easily hide wireframes to render solid colors, outlines, or custom sprites. This guide explains how to disable wireframe rendering during the renderer's initialization, how to toggle it dynamically at runtime, and how to style your physics bodies once wireframes are disabled.

Disabling Wireframes During Initialization

When creating a renderer instance with Matter.Render.create(), pass wireframes: false inside the options object.

const render = Matter.Render.create({
    element: document.body,
    engine: engine,
    options: {
        width: 800,
        height: 600,
        wireframes: false
    }
});

Matter.Render.run(render);

Setting this property to false instructs the built-in canvas renderer to draw filled shapes rather than hollow outlines.

Toggling Wireframes Dynamically

If the renderer is already instantiated, you can disable wireframes at any point by mutating the wireframes property directly on the render instance:

// Disable wireframes
render.options.wireframes = false;

// Re-enable wireframes
render.options.wireframes = true;

This approach is useful for creating debug toggles within your application.

Customizing Body Appearance

Once wireframes are turned off, bodies will render with default solid colors. You can customize the visual appearance of individual bodies using the render configuration block during body creation:

const box = Matter.Bodies.rectangle(400, 200, 80, 80, {
    render: {
        fillStyle: '#e74c3c',      // Fill color (hex, rgb, or color name)
        strokeStyle: '#c0392b',    // Border color
        lineWidth: 3,              // Border width in pixels
        opacity: 1                 // Transparency (0 to 1)
    }
});

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

Applying Sprites and Textures

With wireframes disabled, you can also replace solid shapes with image textures by defining the sprite property:

const ball = Matter.Bodies.circle(400, 100, 40, {
    render: {
        sprite: {
            texture: 'path/to/image.png',
            xScale: 1,
            yScale: 1
        }
    }
});

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

Note that custom colors and sprite textures will not appear on screen if render.options.wireframes remains set to true. Disabling wireframe mode is required for any custom body styling to take effect.