js-particles-factory is a JavaScript library designed to create and animate particles on an HTML canvas element. The particles float around and interact.
This library allows you to customize particles with various shapes, sizes, and behaviors, and provides interactive and visually appealing effects for web applications.
Built with vanilla JS/HTML/CSS
No dependencies
Installation
Usage
Example for a simple usage
API
ParticlesFactory
Particle
License
-
Customizable Particles:
Define shapes (circle, square, rhombus, hexagon, triangle, image), sizes, speed and colors. -
Collision Detection:
Particles can interact with each other and respond to collisions. -
Responsive Design:
Adjusts to window resizing and fullscreen modes. -
Mouse Interaction:
Particles react to mouse movements. -
Flexible Animation Controls:
Start, stop, and adjust particle animation settings. -
Simply adjustable, throttled framerate (requestAnimationFrame)
You can install js-particles-factory via npm:
npm i js-particles-factory --save
Alternatively, include it directly in your HTML head with a script tag:
//*.es.js - gzip 3.5kb
<script type="module" src="https://cdn.jsdelivr.net/gh/BarbWire-1/js-particles-factory/minified/particles-factory.es.js"></script>
Or try the umd.js - 3.26kb
// *.umd.js - gzip
<script type="module" src="https://cdn.jsdelivr.net/gh/BarbWire-1/js-particles-factory/minified/particles-factory.umd.js"></script>
Else copy the particle.factory.es.js into your project and import ParticlesFactory directly.
Create an HTML Canvas Element
<canvas id="particles-canvas"></canvas>
Whether you pass your own config-Object or only pass some changes in an object to the constructor, the defaults get merged with your arguments.
// Default configuration
static defaultConfig = {
canvas: {
id: 'particles-canvas',
width: 500,
height: 500,
},
main: {
frameRate: 30,
numParticles: 80,
speed: 0.2,
mouseDistance: 80,
fillStyle: '#000',
isFullScreen: true,
isResponsive: true,
},
particles: {
shape: 'triangle',
fillStyle: '#ff0000',
randomFill: true,
noFill: false,
stroke: true,
size: 44,
randomSize: true,
draw: true,
collision: false,
opacity: 1,
imageSrc: null
},
lines: {
connectDistance: 100,
strokeStyle: '#ffffff',
draw: true,
lineWidth: 0.5,
opacity: 1,
},
};
import { ParticlesFactory } from 'js-particles-factory';Minimal initialisation with all default settings:
// requires a canvas with the exact id "particles-canvas"
const particles = new ParticlesFactory();Initialisation with eg just another canvasId:
(Note: you need to pass the individual settings as object.)
const particles = new ParticlesFactory({canvas:{id: "your-canvas-id"}});To create and download your own configuration object you can use this interactive version:
const particles = new ParticlesFactory(yourConfigObject);new ParticlesFactory(options)Configuration object for the particle system.
The above passed objects shows the defaultSettings.
Click here for detailed description
-
- id: ID of the canvas element.
- width: Width of the canvas.
- height: Height of the canvas.
- id: ID of the canvas element.
-
- frameRate: Animation frame rate.
- numParticles: Number of particles to generate.
- speed: Base speed of particles.
- mouseDistance: Distance within which particles react to the mouse.
- fillStyle: Background color of the canvas.
- isFullScreen: Toggle fullscreen mode.
- isResponsive: Adjust canvas size on window resize.
- frameRate: Animation frame rate.
-
- shape: Shape of the particles.
- fillStyle: Base color of particles.
- randomFill: Whether particles have random colors.
- noFill: Whether particles are transparent.
- stroke: Whether particles have a stroke.
- size: Base size of particles.
- randomSize: Whether particles have random sizes.
- draw: Whether to draw particles.
- collision: Whether to detect collisions.
- opacity: Opacity of particles.
- imageSrc: The url to an image to use as shape
- shape: Shape of the particles.
-
- connectDistance: Distance within which lines are drawn between particles.
- strokeStyle: Color of the lines.
- draw: Whether to draw lines.
- lineWidth: Width of the lines.
- opacity: Opacity of the lines.
- connectDistance: Distance within which lines are drawn between particles.
-
setFillMode(mode)
Set the fill mode for particles.
Modes: "noFill", "random", "fill". -
setSpeed(newSpeed)
Update the speed of particles. -
setNumParticles(newValue)
Update the number of particles in the system. -
setBaseSize(newBaseSize)
Adjust the new base size of all particles when they're set to randomSize. -
setImageSrc(newUrl)
Create an image to render as particles if shape is set to image -
toggleFullScreen()
Toggle between fullscreen mode and canvas size. -
toggleAnimation()
Start or stop the animation.
The Particle class is not exposed but component of the ParticlesFactory
Click to expand for more details
new Particle(canvas, x, y, size, speed, fillStyle)canvas: The canvas element.
x: X-coordinate of the particle.
y: Y-coordinate of the particle.
size: Size (diameter) of the particle.
speed: Movement speed of the particle.
fillStyle: Color of the particle.
drawParticle(fillColor, opacity, size, shape, strokeStyle)
Draw the particle on the canvas.
keepInBoundaries(drawParticles)
Ensure the particle stays within the canvas boundaries.
particlesCollision(isRandomSize, commonSize, particle, otherParticle, distance)
Handle collisions between particles.
updateCoords(drawParticles)
Recalculate the particle’s coordinates.
updateSpeed(speed)
Update the particle’s speed (on collision).
handleMouseMove(event, mouseDistance, canvasX, canvasY)
Handle the particle's behavior when the mouse moves nearby.
Contributions are welcome! Please submit issues or pull requests via GitHub. For more information on how to contribute, see CONTRIBUTING.md.
This project is licensed under the MIT License - see the LICENSE file for details.