Canvas Particles JS

Description

In an HTML canvas, a bunch of floating particles connected with lines when they approach each other. Creating a fun and interactive background. Colors, interaction and gravity can be customized!

Showcase
Import
Implementation
Class Instantiation
Options
Manually creating particles
One Pager Example

Showcase

If you dont like reading documentation this website is for you:

https://khoeckman.github.io/canvasparticles-js/

Import

Particles will be drawn onto a <canvas> element.

<canvas id="my-canvas"></canvas>

npm

npm install canvasparticles-js
# or
pnpm add canvasparticles-js

ES Module import

import CanvasParticles from 'canvasparticles-js'

If you don't have a bundler:

import CanvasParticles from './node_modules/canvasparticles-js/dist/index.mjs'

Global import

<script src="./node_modules/canvasparticles-js/dist/index.umd.js" defer></script>

No import required in each JavaScript file!

Import with jsDelivr

ES Module import

import CanvasParticles from 'https://cdn.jsdelivr.net/npm/canvasparticles-js/dist/index.min.mjs'

Global import

<script src="https://cdn.jsdelivr.net/npm/canvasparticles-js/dist/index.umd.min.js" defer></script>

Implementation

Start animating

const selector = '#my-canvas' // Query Selector for the canvas
const options = { ... } // See #options
new CanvasParticles(selector, options).start()

Starting and stopping animation

const particles = new CanvasParticles(selector, options)
particles.start()
particles.stop()

To keep the last frame visible when stopping the animation:

particles.stop({ clear: false }) // Default: true

Destruction

Gracefully destroy the instance and remove the canvas element.

particles.destroy()
delete particles // Optional

Class Instantiation

Valid ways to instantiate `CanvasParticles`

const selector = '#my-canvas'
const options = {}
const canvasElement = document.querySelector(selector)

let instance, canvas

// Basic instantiation
instance = new CanvasParticles(selector)
instance = new CanvasParticles(canvasElement)

// Instantiation with custom options
instance = new CanvasParticles(selector, options)
instance = new CanvasParticles(canvasElement, options)

Chaining methods

You can chain .start() for a cleaner syntax:

instance = new CanvasParticles(selector).start()

// Access the canvas directly
canvas = new CanvasParticles(selector).canvas
canvas = new CanvasParticles(selector).start().canvas

Without chaining

If you prefer not to chain methods, you can instantiate first and start later:

instance = new CanvasParticles(selector)
instance.start()
canvas = instance.canvas

Incorrect usage

The following will not return the expected value because CanvasParticles only supports method chaining for .start():

instance = new CanvasParticles(selector).anyOtherMethod()
canvas = new CanvasParticles(selector).anyOtherMethod().canvas

Options

Options to change the particles and their behavior aswell as what happens on MouseMove or Resize events.
Play around with these values in the Sandbox.

Options Object

The default value will be used when an option is assigned an invalid value.

TypeScript Usage: Both float and integer mean number.
integer is used to specify that the number is internally floored to a whole number.

Root options

Option	Type	Default	Description
`background`	`string \| false`	`false`	Canvas background. Any valid CSS `background` value. Ignored when strictly `false`.

`animation`

It's best to not touch these values if it's unclear what it does.

Option	Type	Default	Description
`animation.startOnEnter`	`boolean`	`true`	Start animation when the canvas enters the viewport.
`animation.stopOnLeave`	`boolean`	`true`	Stop animation when the canvas leaves the viewport.

`mouse`

Option	Type	Default	Description
`mouse.interactionType`	`0 \| 1 \| 2`	`2`	Mouse interaction mode. `0 = NONE`, `1 = SHIFT`, `2 = MOVE`.
`mouse.connectDistMult`	`float`	`2/3`	Multiplier applied to `particles.connectDistance` to compute mouse interaction distance.
`mouse.distRatio`	`float`	`2/3`	Controls how strongly particles are pulled toward the mouse. Keep equal to or above `mouse.connectDistMult`.

Interaction types (enum)

NONE (0) – No interaction
SHIFT (1) – Visual displacement only
MOVE (2) – Actual particle movement (default)

`particles`

Option	Type	Default	Description
`particles.generationType`	`0 \| 1 \| 2`	`false`	Auto-generate particles on initialization and when the canvas resizes. `1 = OFF`, `2 = MATCH`
`particles.color`	`string`	`'black'`	Particle and connection color. Any CSS color format.
`particles.ppm`	`integer`	`100`	Particles per million pixels.
`particles.max`	`integer`	`Infinity`	Maximum number of particles allowed.
`particles.maxWork`	`integer`	`Infinity`	Maximum total connection length per particle. Lower values stabilize performance but may flicker.
`particles.connectDistance`	`integer`	`150`	Maximum distance for particle connections (px).
`particles.relSpeed`	`float`	`1`	Relative particle speed multiplier.
`particles.relSize`	`float`	`1`	Relative particle size multiplier.
`particles.rotationSpeed`	`float`	`2`	Direction change speed.
`particles.drawLines`	`boolean`	`true`	Whether to draw lines between particles.

Generation types (enum)

OFF (0) – Never auto-generate particles
NEW (1) – Generate all particles from scratch
MATCH (2) – Add or remove some particles to match the new count (default)

`gravity`

Enabling gravity (repulsive or pulling > 0) performs an extra O(n²) gravity computations per frame.

Option	Type	Default	Description
`gravity.repulsive`	`float`	`0`	Repulsive force between particles.
`gravity.pulling`	`float`	`0`	Attractive force between particles. Requires sufficient repulsion to avoid clustering.
`gravity.friction`	`float`	`0.8`	Damping factor applied to gravitational velocity each update (`0.0 – 1.0`).
`gravity.maxVelocity`	`float`	`Infinity`	Clamp the velocity of each particle to this value to prevent explosions under heavy pulling gravity.

`debug`

Intended for development and debugging. Can be useful to understand internal behavior.

Option	Type	Default	Description
`debug.drawGrid`	`boolean`	`false`	Renders the spatial grid used for partitioning.
`debug.drawIndexes`	`boolean`	`false`	Displays particle indices on the canvas.

Update options on the fly

You can update every option while an instance is animating and it works great; but some options require an extra step.

Using the available setter

These options are the only ones that have and require a dedicated setter to ensure proper integration:

background
mouse.connectDistMult
particles.color

const instance = new CanvasParticles(selector, options)

// Use the setters to update these specific options
instance.setBackground('red')
instance.setMouseConnectDistMult(0.8)
instance.setParticleColor('hsl(149, 100%, 50%)')

Changing the particle count

After updating the following options, the number of particles is not automatically adjusted:

particles.ppm
particles.max

// Note: the backing field is called `option` not `options`!
instance.option.particles.ppm = 100
instance.option.particles.max = 300

The changes are only applied when one of the following methods is called:

instance.newParticles() // Remove all particles and create the correct amount of new ones
instance.matchParticleCount() // Add or remove some particles to match the count

Changing particle properties

After updating the following options, the particles are not automatically updated:

particles.relSize
particles.relSpeed

// Note: the backing field is called `option` not `options`!
instance.option.particles.relSize = 2
instance.option.particles.relSpeed = 3

The changes are only applied when the following method is called:

instance.updateParticles() // Updates the particle.speed and particle.size properties without regenerating any particles

Modifying object properties

All other options can be updated by only modifying the option internal field properties, with changes taking effect immediately.

The new option values are not validated. Assigning invalid values will lead to unexpected behavior. It is therefore recommended to use the options setter.

// Note: the backing field is called `option` not `options`!
instance.option.mouse.interactionType = 0
instance.option.particles.connectDist = 200
instance.option.gravity.repulsive = 1

Updating entire options object

To reinitialize all options, pass a new options object to the options setter.

Existing particles their properties will not be updated automatically. Changing particle properties

instance.options = { ... }

Manually creating particles

createParticle(posX?: number, posY?: number, dir?: number, speed?: number, size?: number)

By default particles.ppm and particles.max are used to auto-generate random particles. To turn this off, set at least one of these properties to 0 or set particles.generationType to OFF (0) (slightly more efficient).

const canvas = '#my-canvas'
const options = {
  particles: {
    generationType: CanvasParticles.generationType.OFF, // = 0
    rotationSpeed: 0,
  },
}
const instance = new CanvasParticles(canvas, options).start()

// Create a horizontal line of particles moving down
for (let x = 0; x < instance.width; x += 4) {
  instance.createParticle(x, 100, 0, 1, 5)
}

// Keep automatically generated particles and remove manually created ones
instance.newParticles({ keepAuto: true, keepManual: false })

One Pager Example

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <style>
      #canvas-particles {
        position: absolute;
        top: 0;
        left: 0;
        width: 100%;
        height: 100%;
        z-index: -1;
      }
    </style>
  </head>

  <body>
    <canvas id="canvas-particles"></canvas>

    <script src="https://cdn.jsdelivr.net/npm/canvasparticles-js/dist/index.umd.js"></script>
    <script>
      const selector = '#canvas-particles'
      const options = {
        background: 'hsl(125, 42%, 35%)',
        mouse: {
          interactionType: CanvasParticles.interactionType.SHIFT, // = 1
        },
        particles: {
          color: 'rgba(150, 255, 105, 0.95)',
          max: 200,
        },
      }
      new CanvasParticles(selector, options).start()
    </script>
  </body>
</html>

Name		Name	Last commit message	Last commit date
Latest commit History 338 Commits
.github/workflows		.github/workflows
demo		demo
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierrc		.prettierrc
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
package.json		package.json
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Canvas Particles JS

Description

Showcase

Import

npm

Import with jsDelivr

Implementation

Start animating

Starting and stopping animation

Destruction

Class Instantiation

Valid ways to instantiate CanvasParticles

Chaining methods

Without chaining

Incorrect usage

Options

Options Object

Root options

animation

mouse

particles

gravity

debug

Update options on the fly

Using the available setter

Changing the particle count

Changing particle properties

Modifying object properties

Updating entire options object

Manually creating particles

One Pager Example

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Valid ways to instantiate `CanvasParticles`

`animation`

`mouse`

`particles`

`gravity`

`debug`

Packages