js-particles-factory

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

Features

• 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)

Installation

You can install js-particles-factory via npm:

npm install js-particles-factory

(includes a *es.js gzip 3.5kb and a *umd.js gzip 3.26kb) Alternatively, include it directly in your HTML head with a script tag:

<script type="module" src="https://cdn.jsdelivr.net/gh/BarbWire-1/js-particles-factory/minified/particles-factory.es.js"></script>

or copy the particle.factory.es.js into your project and import ParticlesFactory directly.

Usage

Basic Setup

Create an HTML Canvas Element

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

Builtin config with default-settings

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,
		},
	};

Initialize the Particle System

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"}});

Instantiate it with your own full config

To create and download your own configuration object you can use this interactive version:

const particles = new ParticlesFactory(yourConfigObject);

API

ParticlesFactory

Constructor:

new ParticlesFactory(options)

Options:

Configuration object for the particle system. The above passed objects shows the defaultSettings.

Configuration Options

• Canvas

  • id: ID of the canvas element.
  • width: Width of the canvas.
  • height: Height of the canvas.

• Main

  • 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.

• Particles

  • 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

• Lines

  • 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.

Methods:

• 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.

Particle

The Particle class is not exposed but component of the ParticlesFactory

Constructor:

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.

Methods:

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.

Contributing

Contributions are welcome! Please submit issues or pull requests via GitHub. For more information on how to contribute, see CONTRIBUTING.md.

License

This project is licensed under the MIT License - see the LICENSE file for details.