How to Import Matter.js into an HTML File

This guide explains how to import and set up the Matter.js 2D physics engine inside a standard HTML document. You will learn the primary methods for loading the library—using a Content Delivery Network (CDN) or hosting the file locally—followed by a minimal working code example to verify that the physics engine is running properly in your browser.

The quickest way to add Matter.js to an HTML file is through a Content Delivery Network (CDN) such as cdnjs or jsDelivr. You do not need to download any files; simply include the <script> tag inside your HTML <head> or just before the closing </body> tag.

Add the following script tag to your HTML file:

<script src="https://cdnjs.cloudflare.com/ajax/libs/matter-js/0.19.0/matter.min.js"></script>

Once loaded, the library exposes a global object named Matter to your JavaScript environment.

Method 2: Import from a Local File

If you prefer to host the library locally or need offline access, follow these steps:

  1. Download the compiled matter.js or matter.min.js file from the official Matter.js GitHub repository releases.
  2. Place the downloaded file into your project folder (for example, in a js/ subfolder).
  3. Reference the file using a relative path within your HTML document:
<script src="js/matter.min.js"></script>

Complete Working Example

Below is a complete, minimal HTML template that imports Matter.js via CDN, creates a physics engine, creates a renderer, and drops a single box onto a static ground:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Matter.js Setup</title>
    <!-- 1. Import the Matter.js library -->
    <script src="https://cdnjs.cloudflare.com/ajax/libs/matter-js/0.19.0/matter.min.js"></script>
    <style>
        body {
            margin: 0;
            overflow: hidden;
        }
    </style>
</head>
<body>
    <script>
        // 2. Alias Matter.js modules for convenience
        const { Engine, Render, Runner, Bodies, Composite } = Matter;

        // 3. Create an engine
        const engine = Engine.create();

        // 4. Create a renderer attached to the document body
        const render = Render.create({
            element: document.body,
            engine: engine,
            options: {
                width: 800,
                height: 600,
                wireframes: false
            }
        });

        // 5. Create a dynamic box and a static ground
        const box = Bodies.rectangle(400, 200, 80, 80);
        const ground = Bodies.rectangle(400, 590, 810, 60, { isStatic: true });

        // 6. Add bodies to the world
        Composite.add(engine.world, [box, ground]);

        // 7. Run the renderer and the engine
        Render.run(render);
        const runner = Runner.create();
        Runner.run(runner, engine);
    </script>
</body>
</html>

Save this code into an index.html file and open it in any modern web browser. If imported correctly, you will see a canvas with a falling box landing on a static platform.