Skip to content
Get packs

Guide · Open source

How to use matter-js: install, build a physics scene and tips

Updated · written with AI from the project's own documentation and checked against our catalogue data

Matter.js is a JavaScript library that simulates how flat (2D) solid objects move, collide, bounce and rest on each other, such as boxes falling onto a pile or balls rolling down a ramp. This guide covers what it is good for, how to install it with npm or a script tag, and where to find working examples. After reading, you will know how to add it to a web page and where to go next.

Matter.jsliabru/matter-js · ★ 18.6k · MIT

Quick start

  1. 1Install Node.js or prepare a page. For npm installs, install Node.js first. For a plain web page, you only need a page that can load a script file.
  2. 2Install the package. Run npm install matter-js in your project folder, or download a stable release.
  3. 3Load the library. Import matter-js in your code or include the matter.js script tag in your web page.
  4. 4Follow the Getting started example. Use the minimal example on the Getting started wiki page as your starting point.
  5. 5Add bodies to a world. Create the rigid bodies your scene needs and add them to the world.
  6. 6Study a demo. Open the examples directory and adapt a demo such as Stack, Pyramid or Car to your project.

What matter-js does and who it is for

Matter.js is a 2D rigid body physics engine for the web. Rigid bodies are solid objects that do not deform, so the library focuses on how boxes and balls move, collide, bounce and come to rest.

It runs in browsers and in Node.js. The README describes it as an original implementation rather than a port of another engine.

  • Good fit: web developers adding physics motion to a canvas or page, hobbyists making small 2D browser games, students learning rigid body physics in code
  • Poor fit: 3D physics (the README describes only a 2D engine), realistic soft materials or fluids, and non-programmers who want a ready-made app

Install matter-js with npm or a script tag

Install matter-js with npm or Yarn. You need Node.js for the npm install. Alternatively, download a stable release or the alpha build and include the script in your web page.

The README gives this npm command:

  • Stable releases are listed on the project's tags page
  • An experimental alpha build is available from the master branch build folder
npm install matter-js

Create a basic physics scene

The README points to the Getting started wiki page for a minimal usage example that should work in both browsers and Node.js. Follow that page for the exact starter code, since this guide does not reproduce it.

Once the library is loaded, the engine simulates the bodies you add to a world. The examples directory in the repository contains the source for all demos, which is the most practical reference for building your own scene.

  • Read the Getting started wiki page for a minimal working example
  • Open the examples directory and copy a demo close to what you need, such as Stack or Pyramid
  • Use the API documentation at brm.io/matter-js/docs for method details

Explore features like collisions, friction and events

The feature list covers rigid and compound bodies, concave and convex hulls, restitution (bounciness), friction, gravity, sleeping and static bodies, constraints, and events. It also includes raycasting, views with translate and zoom, and time scaling for slow motion or speed-up.

The demos are the quickest way to see these features working. The Restitution, Friction and Sensors demos show how the properties change behaviour.

  • Restitution: elastic and inelastic collisions
  • Friction and static friction demos
  • Events and Collision Filtering demos
  • Raycasting and Views demos

Use plugins and tools to extend your project

The engine can be extended through plugins. The README links to guides on using plugins, creating plugins and a list of available plugins. MatterTools is a separate project for creating, testing and debugging worlds.

If you use bundlers or frameworks, the README warns that default configs can reduce real-time performance, especially in development modes. It names Webpack's default sourcemap setting and Vue.js watchers as common causes.

  • Plugins: see the Using plugins and Creating plugins wiki pages
  • MatterTools for creating, testing and debugging worlds
  • Webpack sourcemaps and Vue.js watchers can slow development builds

Build and contribute from source

To build the project locally, the README says you must first install Node.js and pnpm, then run the install and start commands. The start command spawns a development server.

For contribution rules, read CONTRIBUTING.md in the repository.

pnpm install pnpm run start

What people use it for

  • Boxes falling onto a pile, as in the Stack and Pyramid demos
  • A slingshot game using rigid bodies and collisions
  • Newton's Cradle style pendulum scenes
  • Interactive web animations that need objects to bounce and rest
  • Teaching rigid body physics concepts with runnable code

Frequently asked questions

Is matter-js free to use?

Yes. The README states that Matter.js is licensed under The MIT License (MIT), and the license is supplied with the release and source code. Check the license file in the repository for full terms.

How do I install matter-js?

Run npm install matter-js with npm or Yarn. Alternatively, download a stable release or the alpha build and include the matter.js script in your web page with a script tag.

What are the requirements for matter-js?

The README lists Node.js for the npm install, or a web page that can load a script file. It supports Chrome, Firefox, Safari and IE8+ in browsers, and runs in Node.js.

Can matter-js do 3D physics?

No. The README describes matter-js as a 2D rigid body physics engine, so it is not suited to 3D physics projects.

What are alternatives to matter-js?

Comparable projects listed for this item include Box2D (box2d.js ports), planck.js, p2.js and Phaser, which includes Matter physics. Compare them against your project's needs before choosing.

Why is matter-js slow in my project?

The README says bundlers and frameworks may reduce real-time performance with default configs, especially in development modes. For Webpack, check the default sourcemap config, and for Vue.js, check the impact of watchers.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Matter.js suits web developers, hobbyists and students who need lightweight 2D rigid body physics in the browser or Node.js, and it is free under the MIT license. If you need 3D physics, realistic soft materials or fluids, or a ready-made app without coding, pick a different tool.

Install options & downloads