tsParticles - TypeScript Particles

A lightweight TypeScript library for creating particles. Dependency free and browser ready!

Particles.js converted in TypeScript, dependency free, improved with new cool 😎 features and various bugs fixed and it's currently under development!

Do you want to use it on your website?

This library is available on the two most popular CDNs and it's easy and ready to use, if you were using particles.js it's even easier.

You'll find the instructions below, with all the links you need, and don't be scared by TypeScript, it's just the source language.

The output files are just ES5 JavaScript. 🤩

CDNs and npm have all the sources you need in ES5 Javascript, a bundle browser ready (tsparticles.min.js) and all files splitted for import syntax.

Actually the import syntax doesn't have instructions, but you can contact me by mail or in the project's Slack, the link is below and I'll help you find the right solution. Until a guide will be ready this is the fastest solution.

If you are still interested some lines below there are some instructions for migrating from the old particles.js library.

Want to see it in action and try it?

I've created a tsParticles collection on CodePen 😮 or you can checkout my profile

Otherwise there's the demo page link below. Just click/tap the Coronavirus below, don't be scared. It's safe 😷.

Want to see ever more demos? Clone the repository on your computer and follow these instructions

npm install && npm start

Boom! 💥 http://localhost:3000 and you can checkout other demos, if you are brave enough you can switch to the dev branch so you can try the features under development.

Migrating from Particles.js

tsParticles are fully compatible with the particles.js configuration.

Seriously, you just need to change the script source et-voilà, you're ready 🧙!

You can read more here

Want to know 5 reasons to do the switch? Read here

Below you can find all the information you need to install tsParticles and its new syntax.

General Informations

`master`	`staging`	`dev`

Social

Slack

Product Hunt

API Docs

Documentation and Development references here: https://particles.matteobruni.it/docs/ 📖

Library installation

npm

npm install tsparticles

yarn

yarn add tsparticles

NuGet

Hosting / CDN

Please use this host or your own to load tsParticles on your projects

jsDelivr

cdnjs

Usage

Load tsParticles and configure the particles:

index.html

<div id="tsparticles"></div>

<script src="tsparticles.min.js"></script>

app.js

// @path-json can be an object or an array, the first will be loaded directly, the object from the array will be random selected
/* tsParticles.loadJSON(@dom-id, @path-json, @callback (optional)); */
tsParticles.loadJSON("tsparticles", "presets/default.json").then((container) => {
  console.log("callback - tsparticles config loaded");
}).catch((error) => {
  console.error(error);
});

//or

/* tsParticles.load(@dom-id, @options); */
tsParticles.load("tsparticles", { /* options here */ });

//or

/* tsParticles.loadFromArray(@dom-id, @options, @index (optional)); */
tsParticles.loadFromArray("tsparticles", [ { /* options here */ }, { /* other options here */ }]); //random object
tsParticles.loadFromArray("tsparticles", [ { /* options here */ }, { /* other options here */ }], 1); //the second one
// Important! If the index is not in range 0...array.length, the index will be ignored.

// after initialization this can be used.

/* tsParticles.setOnClickHandler(@callback); */
/* this will be fired from all particles loaded */
tsParticles.setOnClickHandler((e) => { /* custom on click handler */ });

// now you can control the animations too, it's possible to pause and resume the animations
// these methods don't change the config so you're safe with all your configurations
// domItem(0) returns the first tsParticles instance loaded in the dom
const particles = tsParticles.domItem(0);
// play will start the animations, if the move is not enabled it won't enable it, it just updates the frame
particles.play();
// pause will stop the animations
particles.pause();

Demo / Generator

https://particles.matteobruni.it/

Characters as particles

Mouse hover connections

Polygon mask

Animated stars

Nyan cat flying on scrolling stars

Snow particles

Background Mask particles

COVID-19 SARS-CoV-2 particles

Don't click! DON'T CLICK! OH NO IT'S SPREADING!!!!

particles.json

{
  "particles": {
    "color": {
      "value": "#ffffff"
    },
    "number": {
      "value": 80,
      "limit": 200,
      "density": {
        "enable": true,
        "area": 800
      }
    },
    "shape": {
      "type": "circle",
      "character": {
        "fill": true,
        "font": "Font Awesome 5 Brands",
        "style": "",
        "value": "\uf179",
        "weight": "400"
      },
      "stroke": {
        "width": 0,
        "color": "#000000"
      },
      "polygon": {
        "sides": 5
      },
      "image": {
        "src": "img/github.svg",
        "width": 100,
        "height": 100
      }
    },
    "opacity": {
      "value": 0.5,
      "random": false,
      "animation": {
        "enable": false,
        "speed": 1,
        "minimumValue": 0.1,
        "sync": false
      }
    },
    "rotate": {
      "value": 0,
      "random": true,
      "direction": "clockwise",
      "animation": {
        "enable": true,
        "speed": 5,
        "sync": false
      }
    },
    "size": {
      "value": 10,
      "random": true,
      "animation": {
        "enable": false,
        "speed": 80,
        "minimumValue": 0.1,
        "sync": false
      }
    },
    "lineLinked": {
      "enable": true,
      "distance": 300,
      "color": "#ffffff",
      "opacity": 0.4,
      "width": 2
    },
    "move": {
      "enable": true,
      "speed": 12,
      "direction": "none",
      "random": false,
      "straight": false,
      "outMode": "out",
      "bounce": false,
      "trail": {
        "enable": false,
        "length": 10,
        "fillColor": "#000000"      
      },
      "attract": {
        "enable": false,
        "rotateX": 600,
        "rotateY": 1200
      }
    }
  },
  "interactivity": {
    "detectsOn": "canvas",
    "events": {
      "onHover": {
        "enable": false,
        "mode": "repulse"
      },
      "onClick": {
        "enable": true,
        "mode": "push"
      },
      "resize": true
    },
    "modes": {
      "connect": {
        "distance": 80,
        "lineLinked": {
          "opacity": 0.5
        },
        "radius": 60
      },
      "grab": {
        "distance": 800,
        "lineLinked": {
          "opacity": 1
        }
      },
      "bubble": {
        "distance": 800,
        "size": 80,
        "duration": 2,
        "opacity": 0.8,
        "speed": 3
      },
      "repulse": {
        "distance": 400,
        "duration": 0.4
      },
      "push": {
        "quantity": 4
      },
      "remove": {
        "quantity": 2
      }
    }
  },
  "detectRetina": true,
  "fpsLimit": 60,
  "pauseOnBlur": true,
  "backgroundMask": {
    "enable": true,
    "cover": {
      "value": {
        "r": 255,
        "g": 255,
        "b": 255
      }
    }
  },
  "polygon": {
    "debug": {
      "enable": true,
      "color": "#000000"
    },
    "type": "inside",
    "move": {
      "radius": 10
    },
    "url": "demo/svg/deer.svg"
  }
}

Options

key	option type / notes	example
`particles.number.value`	number	`40`
`particles.number.limit`	number	`200` / `0` or less disables the limit
`particles.number.density.enable`	boolean	`true` / `false`
`particles.number.density.area`	number	`800`
`particles.color.value`	HEX (string) RGB (object) HSL (object) array selection (HEX) random (string)	`"#0d47a1"` `{r:182, g:25, b:36}` `{h:356, s:76, l:41}` `["#b61924", "#333333", "999999"]` `"random"`
`particles.shape.type`	string array selection	`"circle"` `"line"` `"edge"` `"triangle"` `"polygon"` `"star"` `"image"` `["circle", "triangle", "image"]`
`particles.shape.stroke.width`	number	`2`
`particles.shape.stroke.color`	HEX (string) random (string)	`"#222222"` `"random"`
`particles.shape.polygon.sides`	number	`5`
`particles.shape.character`	object / array	A single character object like below or an array of the same objects
`particles.shape.character.value`	object / array	`\uf179` / `*`
`particles.shape.character.font`	string	`Font Awesome 5 Brands`
`particles.shape.character.style`	string	``
`particles.shape.character.weight`	string	`400` (Font weight, for FontAwesome it's required to use the exact weight for every family, Chrome won't render correctly otherwise.)
`particles.shape.character.fill`	boolean	`true` / `false` (Fills or strokes the text. If the fonts doesn't support the stroke or the fill you won't see any particle. FontAwesome requires `fill: true`)
`particles.shape.image`	object / array	A single image object like below or an array of the same objects
`particles.shape.image.src`	path link svg / png / gif / jpg	`"assets/img/yop.svg"` `"http://mywebsite.com/assets/img/yop.png"`
`particles.shape.image.width`	number (for aspect ratio)	`100`
`particles.shape.image.height`	number (for aspect ratio)	`100`
`particles.opacity.value`	number (0 to 1)	`0.75`
`particles.opacity.random`	boolean	`true` / `false`
`particles.opacity.animation.enable`	boolean	`true` / `false`
`particles.opacity.animation.speed`	number	`3`
`particles.opacity.animation.minimumValue`	number (0 to 1)	`0.25`
`particles.opacity.animation.sync`	boolean	`true` / `false`
`particles.rotate.value`	number (angle in degrees)	`45`
`particles.rotate.random`	boolean	`true` / `false`
`particles.rotate.direction`	string	`clockwise` / `counterclockwise`
`particles.rotate.animation.enable`	boolean	`true` / `false`
`particles.rotate.animation.speed`	number	5
`particles.rotate.animation.sync`	boolean	`true` / `false`
`particles.size.value`	number	`20`
`particles.size.random`	boolean	`true` / `false`
`particles.size.animation.enable`	boolean	`true` / `false`
`particles.size.animation.speed`	number	`3`
`particles.size.animation.minimumValue`	number	`0.25`
`particles.size.animation.sync`	boolean	`true` / `false`
`particles.lineLinked.enable`	boolean	`true` / `false`
`particles.lineLinked.distance`	number	`150`
`particles.lineLinked.color`	HEX (string) random (string)	`#ffffff` `"random"`
`particles.lineLinked.opacity`	number (0 to 1)	`0.5`
`particles.lineLinked.width`	number	`1.5`
`particles.move.enable`	boolean	`true` / `false`
`particles.move.speed`	number	`4`
`particles.move.direction`	string	`"none"` `"top"` `"top-right"` `"right"` `"bottom-right"` `"bottom"` `"bottom-left"` `"left"` `"top-left"`
`particles.move.random`	boolean	`true` / `false`
`particles.move.straight`	boolean	`true` / `false`
`particles.move.outMode`	string (out of canvas)	`"out"` `"destroy"` `"bounce"` `"bounce-vertical"` `"bounce-horizontal"`
`particles.move.bounce`	boolean (between particles)	`true` / `false`
`particles.move.trail.enable`	boolean	`true` / `false`
`particles.move.trail.length`	number	`10`
`particles.move.trail.fillColor`	HEX (string)	`#000000`
`particles.move.attract.enable`	boolean	`true` / `false`
`particles.move.attract.rotate.x`	number	`3000`
`particles.move.attract.rotate.y`	number	`1500`
`interactivity.detectsOn`	string	`"canvas", "window","parent"`
`interactivity.events.onHover.enable`	boolean	`true` / `false`
`interactivity.events.onHover.mode`	string array selection	`"grab"` `"bubble"` `"repulse"` `"connect"` `["grab", "bubble"]`
`interactivity.events.onClick.enable`	boolean	`true` / `false`
`interactivity.events.onClick.mode`	string array selection	`"push"` `"remove"` `"bubble"` `"repulse"` `["push", "repulse"]`
`interactivity.events.onDiv.mnode`	string array selection	`"repulse"` `["repulse"]`
`interactivity.events.onDiv.enable`	boolean	`true` / `false`
`interactivity.events.onDiv.el`	string	`repulse-div`
`interactivity.events.resize`	boolean	`true` / `false`
`interactivity.events.modes.connect.distance`	number	`100`
`interactivity.events.modes.connect.radius`	number	`60`
`interactivity.events.modes.connect.lineLinked.opacity`	number (0 to 1)	`0.75`
`interactivity.events.modes.grab.distance`	number	`100`
`interactivity.events.modes.grab.lineLinked.opacity`	number (0 to 1)	`0.75`
`interactivity.events.modes.bubble.distance`	number	`100`
`interactivity.events.modes.bubble.size`	number	`40`
`interactivity.events.modes.bubble.duration`	number (second)	`0.4`
`interactivity.events.modes.repulse.distance`	number	`200`
`interactivity.events.modes.repulse.duration`	number (second)	`1.2`
`interactivity.events.modes.push.quantity`	number	`4`
`interactivity.events.modes.remove.quantity`	number	`4`
`detectRetina`	boolean	`true` / `false`
`fpsLimit`	number	`60`
`pauseOnBlur`	boolean	`true` / `false`
`backgroundMask.enable`	boolean	`true` / `false`
`backgroundMask.cover.value`	HEX (string) RGB (object) HSL (object) random (string)	`"#0d47a1"` `{r:182, g:25, b:36}` `{h:356, s:76, l:41}` `"random"`
`polygon.enable`	boolean	`true` / `false`
`polygon.draw.enable`	boolean	`true` / `false`
`polygon.draw.lineWidth`	number	`0.5`
`polygon.draw.lineColor`	HEX (string)	`#ffffff`
`polygon.scale`	number	1
`polygon.type`	string	`none` / `inside` / `outside` / `inline`
`polygon.move.radius`	number	`10`
`polygon.url`	string	`demo/svg/deer.svg`

dimitriosp/tsparticles