Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/barbwire-1/js-particles-factory
a JavaScript library designed to create and animate particles on an HTML canvas element. The particles float around and interact. Create your favourite config at netlify
https://github.com/barbwire-1/js-particles-factory
animation easy2use js lightweight particles
Last synced: 3 days ago
JSON representation
a JavaScript library designed to create and animate particles on an HTML canvas element. The particles float around and interact. Create your favourite config at netlify
- Host: GitHub
- URL: https://github.com/barbwire-1/js-particles-factory
- Owner: BarbWire-1
- Created: 2024-07-24T19:21:08.000Z (4 months ago)
- Default Branch: main-branch
- Last Pushed: 2024-07-26T15:45:38.000Z (4 months ago)
- Last Synced: 2024-07-26T22:59:45.652Z (4 months ago)
- Topics: animation, easy2use, js, lightweight, particles
- Language: JavaScript
- Homepage: https://particles-factory.netlify.app/
- Size: 2.22 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# 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](#installation)
[Usage](#usage)
[Example for a simple usage](https://github.com/BarbWire-1/js-particles-factory-example)
[API](#api)
[ParticlesFactory](#particlesfactory)
[Particle](#particle)
[License](#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 i js-particles-factory --save
```
Alternatively, include it directly in your HTML head with a script tag:
```
//*.es.js - gzip 3.5kb
```
Or try the umd.js - 3.26kb
```
// *.umd.js - gzip
```
Else copy the [particle.factory.es.js](./minified/particles-factory.es.js) into your project and import **ParticlesFactory** directly.
---
## Usage
### Basic Setup
Create an HTML Canvas Element
```
```
### 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.
```js
// 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
```js
import { ParticlesFactory } from 'js-particles-factory';
```
Minimal initialisation with all default settings:
```js
// 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.)
```js
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:
[](https://particles-factory.netlify.app/)
```js
const particles = new ParticlesFactory(yourConfigObject);
```
---
## API
## ParticlesFactory
#### Constructor:
```js
new ParticlesFactory(options)
```
#### Options:
Configuration object for the particle system.
The above passed objects shows the defaultSettings.
## Configuration Options
Click here for detailed description
* ### 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
Click to expand for more details
### Constructor:
```js
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.