Skip to content
Get packs

Guide · Open source

How to use particles.js: install, configure and customise

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

particles.js is an open-source JavaScript library that draws a lightweight 2D canvas animation of moving dots, with optional lines connecting them, behind or on top of a web page. This guide shows you how to install it, load it into a div, and tune the look and behaviour through a JSON config file. By the end you will be able to add a working particle background to a page and adjust its main settings.

particles.jsVincentGarreau/particles.js · ★ 30.2k · MIT

Quick start

  1. 1Install the package. Run npm install particles.js in your project folder.
  2. 2Add the container div. Place a div with the id particles-js where the animation should show.
  3. 3Include the script. Load particles.js with a script tag in your HTML.
  4. 4Create a JSON config. Copy the README example into assets/particles.json or use the online generator to export one.
  5. 5Call particlesJS.load. Pass the div id and the JSON path to particlesJS.load, with an optional callback.
  6. 6Tune and test. Change one setting at a time, reload, and check the result in your browser.

Install particles.js with npm

The library is available as a package on npm. The README lists the install command below. It does not list any prerequisites.

Packages for Bower, Rails Assets and Meteor are also listed in the README, along with a jsDelivr host option if you prefer to load the file from a CDN.

npm install particles.js

Add the container and script to your page

Place an empty div with the id particles-js where you want the animation to appear, then load particles.js with a script tag. The README example uses a local file named particles.js in the same folder as index.html.

<div id="particles-js"></div> <script src="particles.js"></script>

Load the configuration with particlesJS.load

Call particlesJS.load with the id of your div, the path to a JSON config file, and an optional callback that runs once the config has loaded. The README comment describes the signature as particlesJS.load(@dom-id, @path-json, @callback (optional)).

In the README example the config file is assets/particles.json. The callback in the example only logs a message to the console.

  • First argument: the dom id, here particles-js (no hash symbol)
  • Second argument: the path to the JSON file, here assets/particles.json
  • Third argument (optional): a callback function
particlesJS.load('particles-js', 'assets/particles.json', function() { console.log('callback - particles.js config loaded'); });

Configure particles in the JSON file

The config file has two main blocks: particles controls the dots themselves (number, color, shape, opacity, size, line links and movement), and interactivity controls what happens on hover and click. The README also sets retina_detect to true at the top level.

The README example config is a full working starting point. Copy it, then change one value at a time and reload the page to see the effect.

  • particles.number.value: how many particles appear (the example uses 80)
  • particles.color.value: the particle colour, for example "#ffffff"
  • particles.shape.type: circle, edge, triangle, polygon, star, image, or an array to mix shapes
  • particles.line_linked.enable and distance: whether lines join nearby particles and how far apart they can be
  • particles.move.speed and direction: how fast particles move and which way (none, top, bottom-left and so on)
  • interactivity.events.onclick.mode: the effect on click, such as push or remove

Use the generator to build a config

The README links to an online generator where you can tune settings, export a config, and share it. It also links to a CodePen demo. Use the generator to find values you like, then save the exported JSON as your config file. The README does not describe the generator's exact export steps, so check what the page offers.

Check the options table before you change settings

The README includes an options table with the key, type and an example for each setting. Some examples are useful: opacity values run from 0 to 1, color.value accepts a HEX string, an RGB object, an HSL object, an array of colours, or the word random.

The README itself warns that the options table is a summary and may not match all behaviour. If a setting does not do what you expect, test it in a small page first.

  • Color can be "#b61924", {r:182, g:25, b:36}, {h:356, s:76, l:41}, an array, or "random"
  • Opacity values range from 0 to 1
  • Interactivity modes include grab, bubble, repulse, push and remove

What people use it for

  • Adding an animated background to a landing page or hero section
  • Prototyping a particle effect without writing animation code
  • Using a simple JSON-configured effect on a static site
  • Showing custom image shapes, such as an SVG logo, as particles

Frequently asked questions

Is particles.js free to use?

particles.js is released under the MIT licence, as listed in the project details. Check the LICENSE file in the repository for the full terms before using it in a commercial project.

How do I install particles.js?

The README gives the npm command npm install particles.js. Bower, Rails Assets and Meteor install options are also listed there.

Does particles.js need any prerequisites?

The README does not list any prerequisites. It is a JavaScript library loaded into a web page with a script tag.

Can I use particles.js for 3D effects?

Not really. The README describes only a lightweight 2D canvas effect, so projects needing complex 3D or high-performance game-style graphics should look elsewhere.

What are the alternatives to particles.js?

The project details list tsParticles, Particles.js Lite and Vanta.js as comparable projects. Compare them on the features you need before choosing.

Is particles.js still maintained?

The last push shown in the project details is March 2024. If you need a currently maintained dependency, check the repository activity before adopting it.

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

particles.js suits web developers and designers who want a simple, JSON-configured animated background for a landing page or static site. It is a poor fit if you need 3D graphics, detailed documentation for every option, or a dependency that is actively maintained, so consider tsParticles or Vanta.js for those cases.

Install options & downloads