tsparticles
Version:
Easily create highly customizable particle animations and use them as animated backgrounds for your website. Ready to use components available also for React, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Riot.js, Inferno.
370 lines (215 loc) • 12.8 kB
Markdown
[](https://particles.js.org)
# tsParticles - TypeScript Particles
**A lightweight TypeScript library for creating particles. Dependency free (\*), browser ready and compatible with
React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Riot.js, Solid.js, and Web Components**
[](https://openbase.com/js/tsparticles?utm_source=embedded&utm_medium=badge&utm_campaign=rate-badge) [](https://www.jsdelivr.com/package/npm/tsparticles) [](https://cdnjs.com/libraries/tsparticles) [](https://www.npmjs.com/package/tsparticles) [](https://www.npmjs.com/package/tsparticles) [](https://lerna.js.org/) [](https://www.codefactor.io/repository/github/matteobruni/tsparticles) [](https://www.codacy.com/manual/ar3s/tsparticles?utm_source=github.com&utm_medium=referral&utm_content=matteobruni/tsparticles&utm_campaign=Badge_Grade)
[](https://join.slack.com/t/tsparticles/shared_invite/enQtOTcxNTQxNjQ4NzkxLWE2MTZhZWExMWRmOWI5MTMxNjczOGE1Yjk0MjViYjdkYTUzODM3OTc5MGQ5MjFlODc4MzE0N2Q1OWQxZDc1YzI) [](https://discord.gg/hACwv45Hme)
[](https://www.producthunt.com/posts/tsparticles?utm_source=badge-featured&utm_medium=badge&utm_souce=badge-tsparticles")
## Do you want to use it on your website?
_Documentation and Development references [here](https://particles.js.org/docs/) 📖_
**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](https://github.com/matteobruni/tsparticles/blob/main/README.md#library-installation), with all the
links you need, and _don't be scared by **TypeScript**, it's just the source language_.
**The output files are just JavaScript**. 🤩
CDNs and `npm` have all the sources you need in **Javascript**, a bundle browser ready (tsparticles.min.js) and all
files splitted for `import` syntax.
**If you are still interested** some lines below there are some instructions for migrating from the old particles.js
library.
## **_Library installation_**
### **_Hosting / CDN_**
**_Please use this hosts or your own to load tsParticles on your projects_**
#### jsDelivr
[](https://www.jsdelivr.com/package/npm/tsparticles)
#### cdnjs
[](https://cdnjs.com/libraries/tsparticles)
#### unpkg
<https://unpkg.com/tsparticles/>
### **_npm_**
[](https://www.npmjs.com/package/tsparticles) [](https://www.npmjs.com/package/tsparticles)
```shell
npm install tsparticles
```
### **_yarn_**
```shell
yarn add tsparticles
```
#### Import and require
Starting from version 1.12.11 `import` and `require` can be used to import `tsParticles` .
Now you can write something like this
```javascript
const tsParticles = require("tsparticles");
// or
import { tsParticles } from "tsparticles";
```
The imported `tsParticles` is the same instance you have when including the script.
### **_NuGet_**
[](https://www.nuget.org/packages/tsParticles/)
### **_Usage_**
Load tsParticles and configure the particles:
[](https://particles.js.org)
**index.html**
```html
<div id="tsparticles"></div>
<script src="tsparticles.min.js"></script>
```
**app.js**
```javascript
// @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((event, particles) => {
/* 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();
```
## Official components for some of the most used frameworks
### Angular
#### `ng-particles`
[](https://www.npmjs.com/package/ng-particles) [](https://www.npmjs.com/package/ng-particles)
You can find the instructions [here](https://github.com/matteobruni/tsparticles/blob/main/components/angular/README.md)
### Inferno
#### `inferno-particles`
[](https://www.npmjs.com/package/inferno-particles) [](https://www.npmjs.com/package/inferno-particles)
You can find the instructions [here](https://github.com/matteobruni/tsparticles/blob/main/components/inferno/README.md)
### jQuery
#### `jquery-particles`
[](https://www.npmjs.com/package/jquery-particles) [](https://www.npmjs.com/package/jquery-particles)
You can find the instructions [here](https://github.com/matteobruni/tsparticles/blob/main/components/jquery/README.md)
### Preact
#### `preact-particles`
[](https://www.npmjs.com/package/preact-particles) [](https://www.npmjs.com/package/preact-particles)
You can find the instructions [here](https://github.com/matteobruni/tsparticles/blob/main/components/preact/README.md)
### ReactJS
#### `react-tsparticles`
[](https://www.npmjs.com/package/react-tsparticles) [](https://www.npmjs.com/package/react-tsparticles)
You can find the instructions [here](https://github.com/matteobruni/tsparticles/blob/main/components/react/README.md)
### Svelte
#### `svelte-particles`
[](https://www.npmjs.com/package/svelte-particles) [](https://www.npmjs.com/package/svelte-particles)
You can find the instructions [here](https://github.com/matteobruni/tsparticles/blob/main/components/svelte/README.md)
### VueJS 2.x
#### `particles.vue`
[](https://www.npmjs.com/package/particles.vue) [](https://www.npmjs.com/package/particles.vue)
You can find the instructions [here](https://github.com/matteobruni/tsparticles/blob/main/components/vue/README.md)
### VueJS 3.x
#### `particles.vue3`
[](https://www.npmjs.com/package/particles.vue3) [](https://www.npmjs.com/package/particles.vue3)
You can find the instructions [here](https://github.com/matteobruni/tsparticles/blob/main/components/vue3/README.md)
## **_Demo / Generator_**
<https://particles.js.org/>
[](https://particles.js.org/)
### Characters as particles
[](https://particles.js.org/#chars)
### Mouse hover connections
[](https://particles.js.org/#connect)
### Polygon mask
[](https://particles.js.org/#polygonMask)
### Animated stars
[](https://particles.js.org/#nasa)
### Nyan cat flying on scrolling stars
[](https://particles.js.org/#nyancat2)
### Snow particles
[](https://particles.js.org/#snow)
### Background Mask particles
[](https://particles.js.org/#background)
#### COVID-19 SARS-CoV-2 particles
[](https://particles.js.org/#virus)
_Don't click! DON'T CLICK! OH NO IT'S SPREADING!!!!_
**COVID-19 is a serious disease. Please stay at home, wear a mask and stay safe!**
**particles.json**
You can find a sample config [here](https://particles.js.org/docs/modules/_core_container_.html) 📖
## **_Options_**
You can find all options
available [here](https://particles.js.org/docs/interfaces/_options_interfaces_ioptions_.ioptions.html) 📖
## Want to see it in action and try it?
I've created a tsParticles collection on [CodePen](https://codepen.io/collection/DPOage) 😮 or you can checkout
my [profile](https://codepen.io/matteobruni)
Otherwise there's the demo page link below. Just click/tap the Coronavirus below, don't be scared. **It's safe** 😷.
[](https://particles.js.org/#virus)
Want to see ever more demos? Clone the repository on your computer and follow these instructions
```shell
yarn install && yarn start
```
**Boom! 💥** <http://localhost:3000> and you can checkout other demos.
_If you are brave enough_ you can switch to the `dev` branch for trying the features under development.
## Dependencies
You may have notices the \* near dependency free. Well almost all features works without any dependency, but... Well
there's a little but. The **Polygon Mask** feature requires `[pathseg](https://github.com/progers/pathseg)` for some
browsers to work fine, and obviously the Icon Fonts (like `FontAwesome` ) must be included in your page.
## Migrating from Particles.js
**tsParticles** library is 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](https://dev.to/matteobruni/migrating-from-particles-js-to-tsparticles-2a6m)**
Want to know 5 reasons to do the
switch? [Read here](https://dev.to/matteobruni/5-reasons-to-use-tsparticles-and-not-particles-js-1gbe)
_Below you can find all the information you need to install tsParticles and its new syntax._
## Plugins/Customizations
tsParticles now supports some customizations 🥳.
**You can create your own plugins**
_Read more [here](https://particles.js.org/docs/modules/_core_interfaces_iplugin_.html)...\_