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

Table of Contents

• tsParticles - TypeScript Particles
  • Table of Contents
  • Do you want to use it on your website?
  • Library installation
    • Hosting / CDN
      • jsDelivr
      • cdnjs
      • unpkg
    • npm
    • yarn
    • pnpm
      • Import and require
    • Usage
  • Official components for some of the most used frameworks
    • Angular
      • @tsparticles/angular
    • Astro
      • astro-particles
    • Ember.js
      • ember-tsparticles
    • Inferno
      • inferno-particles
    • jQuery
      • jquery-particles
    • Preact
      • preact-particles
    • ReactJS
      • @tsparticles/react
    • RiotJS
      • riot-particles
    • SolidJS
      • solid-particles
    • Svelte
      • @tsparticles/svelte
    • VueJS 2.x
      • @tsparticles/vue2
    • VueJS 3.x
      • @tsparticles/vue3
    • Web Components
      • web-particles
    • WordPress
      • @tsparticles/wordpress
    • Elementor
  • Presets
    • Big Circles
    • Bubbles
    • Confetti
    • Fire
    • Firefly
    • Fireworks
    • Fountain
    • Links
    • Sea Anemone
    • Snow
    • Stars
    • Triangles
  • Templates and Resources
  • Demo / Generator
  • Video Tutorials
    • Characters as particles
    • Polygon mask
    • Animated stars
    • Nyan cat flying on scrolling stars
    • Snow particles
    • Background Mask particles
  • Options
  • Want to see it in action and try it?
  • Migrating from Particles.js
  • Plugins/Customizations
  • Dependency Graph
  • Sponsors
    • Huge thanks to JetBrains for the 2020-2022 Open Source Licenses!

Do you want to use it on your website?

Documentation and Development references here 📖

This library is available on two of the 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 JavaScript. 🤩

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

If you are interested there are some simple instructions just below to guide you to migrate from the old particles.js library.

Library installation

Hosting / CDN

Please use these hosts or your own to load tsParticles on your projects

jsDelivr

cdnjs

unpkg

https://unpkg.com/@tsparticles/confetti/ https://unpkg.com/@tsparticles/engine/ https://unpkg.com/@tsparticles/fireworks/ https://unpkg.com/@tsparticles/basic/ https://unpkg.com/@tsparticles/slim/ https://unpkg.com/tsparticles/ https://unpkg.com/@tsparticles/all/

npm

tsParticles Confetti

tsParticles Engine

tsParticles Fireworks

tsParticles Basic

tsParticles Slim

tsParticles

tsParticles All

1npm install @tsparticles/engine

yarn

1yarn add @tsparticles/engine

pnpm

1pnpm install @tsparticles/engine

Import and require

1const tsParticles = require("@tsparticles/engine");
2
3// or
4
5import { tsParticles } from "@tsparticles/engine";

The imported tsParticles is the same instance you have when including the script in the page using the <script> tag.

Usage

Load tsParticles and configure the particles:

index.html

1<div id="tsparticles"></div>
2
3<script src="tsparticles.engine.min.js"></script>

app.js

1// @path-json can be an object or an array, the first will be loaded directly, and the object from the array will be randomly selected
2/* tsParticles.load(@params); */
3
4tsParticles
5    .load({
6        id: "tsparticles",
7        url: "presets/default.json",
8    })
9    .then(container => {
10        console.log("callback - tsparticles config loaded");
11    })
12    .catch(error => {
13        console.error(error);
14    });
15
16//or
17
18tsParticles.load({
19    id: "tsparticles",
20    options: {
21        /* options here */
22    },
23});
24
25//or
26
27tsParticles.load({
28    id: "tsparticles",
29    options: [
30        {
31            /* options here */
32        },
33        {
34            /* other options here */
35        },
36    ],
37});
38//random object
39
40tsParticles.load({
41    id: "tsparticles",
42    options: [
43        {
44            /* options here */
45        },
46        {
47            /* other options here */
48        },
49    ],
50    index: 1,
51}); //the second one
52// Important! If the index is not in range 0...<array.length, the index will be ignored.
53
54// after initialization this can be used.
55
56/* tsParticles.setOnClickHandler(@callback); */
57
58/* this will be fired from all particles loaded */
59
60tsParticles.setOnClickHandler((event, particles) => {
61    /* custom on click handler */
62});
63
64// now you can control the animations too, it's possible to pause and resume the animations
65// these methods don't change the config so you're safe with all your configurations
66// domItem(0) returns the first tsParticles instance loaded in the dom
67const particles = tsParticles.domItem(0);
68
69// play will start the animations, if the move is not enabled it won't enable it, it just updates the frame
70particles.play();
71
72// pause will stop the animations
73particles.pause();

Official components for some of the most used frameworks

Angular

@tsparticles/angular

Instructions available here

Astro

astro-particles

Instructions available here

Ember.js

ember-tsparticles

Instructions available here

Inferno

inferno-particles

Instructions available here

jQuery

jquery-particles

Instructions available here

Preact

preact-particles

Instructions available here

ReactJS

@tsparticles/react

Instructions available here

RiotJS

riot-particles

You can find the instructions here

SolidJS

solid-particles

You can find the instructions here

Svelte

@tsparticles/svelte

Instructions available here

VueJS 2.x

@tsparticles/vue2

Instructions available here

VueJS 3.x

@tsparticles/vue3

Instruction available here

Web Components

web-particles

You can find the instructions here

WordPress

@tsparticles/wordpress

The plugin page hosted on WordPress.org can be found here

Elementor

Actually, an official tsParticles plugin isn't existing, but I have a collaboration with the Premium Addons for Elementor plugin collection.

Presets

There are some presets ready to be used in this repository, and they also have a bundle file that contains everything needed to run.

Big Circles

This preset loads big colored circles moving upwards on a white background.

You can find the instructions here

Bubbles

This preset loads colored bubbles coming from the bottom of the screen on a white background.

You can find the instructions here

Confetti

This preset loads white and red confetti launched from the screen center on a transparent background.

You can find the instructions here

Fire

This preset loads a faded red to a black background with particles colored like fire and ash sparks.

You can find the instructions here

Firefly

This preset loads a mouse trail made with small fading particles like little fireflies.

You can find the instructions here

Fireworks

This preset loads a beautiful fireworks effect.

You can find the instructions here

Fountain

You can find the instructions here

Links

You can find the instructions here

Sea Anemone

You can find the instructions here

Snow

You can find the instructions here

Stars

You can find the instructions here

Triangles

You can find the instructions here

Templates and Resources

You can find some tsParticles related templates here. The templates are created for Vanilla Javascript, ReactJS, VueJS, Angular, SvelteJS, and other frameworks.

The templates will vary, new ones can be created or older ones updated with the latest features or changed to a better style. Check them out once in a while.

If you created some good design with tsParticles feel free to submit a pull request with your cool template, you'll be credited as the template author!

https://github.com/tsparticles/templates

Demo / Generator

https://particles.js.org/samples

Video Tutorials

You can find all video tutorials on the website here: https://particles.js.org/video.html

More videos are coming soon! Check every day if there are some new contents.

Characters as particles

Polygon mask

Animated stars

Nyan cat flying on scrolling stars

Snow particles

Background Mask particles

particles.json

You can find some config samples here 📖

Options

You can find all options available here 📖

Want to see it in action and try it?

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

Otherwise, there's the demo page link below.

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

1$ pnpm i
2$ pnpm run build
3$ cd demo/vanilla
4$ pnpm start

Boom! 💥 http://localhost:3000 and you can check out other demos.

If you are brave enough you can switch to the dev branch for trying the features under development.

Migrating from Particles.js

tsParticles has a package that makes this library 100% compatible with the particles.js configuration.

Seriously, you just need to change the script from particles.js to the bundled compatibility package, 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.

Plugins/Customizations

tsParticles now supports some customizations 🥳.

You can create your own plugins

Read more here...

Dependency Graph

1flowchart TD
2
3  subgraph core [Core]
4    engine[tsParticles Engine]
5    perlin-noise[Perlin Noise Lib]
6    simplex-noise[Simplex Noise Lib]
7    configs[tsParticles Configs]
8  end
9
10  subgraph bundle-basic [tsParticles Basic]
11
12    subgraph basic-movers [Movers]
13      move-base[Base]
14    end
15
16    subgraph basic-shapes [Shapes]
17      shape-circle[Circle]
18    end
19
20    subgraph basic-updates [Updaters]
21      updater-color[Color]
22      updater-opacity[Opacity]
23      updater-out-modes[Out Modes]
24      updater-size[Size]
25    end
26
27  end
28
29  engine --> bundle-basic
30
31  subgraph bundle-confetti [tsParticles Confetti]
32
33    subgraph confetti-plugins [Plugins]
34      plugin-emitters
35      plugin-motion
36    end
37
38    subgraph confetti-shapes [Shapes]
39      shape-cards
40      shape-emoji
41      shape-heart
42      shape-image
43      shape-polygon
44      shape-square
45      shape-star
46    end
47
48    subgraph confetti-updaters [Updaters]
49      updater-life
50      updater-roll
51      updater-rotate
52      updater-tilt
53      updater-wobble
54    end
55
56  end
57
58  bundle-basic --> bundle-confetti
59
60  subgraph bundle-slim [tsParticles Slim]
61
62    subgraph slim-interactions [Interactions]
63
64      subgraph slim-interactions-external [Externals]
65        interaction-external-attract[Attract]
66        interaction-external-bounce[Bounce]
67        interaction-external-bubble[Bubble]
68        interaction-external-connect[Connect]
69        interaction-external-grab[Grab]
70        interaction-external-pause[Pause]
71        interaction-external-push[Push]
72        interaction-external-remove[Remove]
73        interaction-external-repulse[Repulse]
74        interaction-external-slow[Slow]
75      end
76
77      subgraph slim-interactions-particles [Particles]
78        interaction-particles-attract[Attract]
79        interaction-particles-collisions[Collisions]
80        interaction-particles-links[Links]
81      end
82
83    end
84
85    subgraph slim-movers [Movers]
86      move-parallax[Parallax]
87    end
88
89    subgraph slim-plugins [Plugins]
90
91      subgraph slim-plugins-easings [Easings]
92        plugin-easing-quad[Quad]
93      end
94
95    end
96
97    subgraph slim-shapes [Shapes]
98      shape-emoji[Emoji]
99      shape-image[Image]
100      shape-line[Line]
101      shape-polygon[Polygon]
102      shape-square[Square]
103      shape-star[Star]
104    end
105
106    subgraph slim-updaters [Updaters]
107      updater-life[Life]
108      updater-rotate[Rotate]
109      updater-stroke-color[Stroke Color]
110    end
111
112  end
113
114  bundle-basic --> bundle-slim
115
116  subgraph bundle-fireworks [tsParticles Fireworks]
117
118    subgraph fireworks-effects [Effects]
119      effect-trail
120    end
121
122    subgraph fireworks-plugins [Plugins]
123      plugin-emitters
124
125      subgraph fireworks-plugin-emitters-shapes [Emitters Shapes]
126        plugin-emitters-shape-square
127      end
128
129      plugin-sounds
130    end
131
132    subgraph fireworks-updaters [Updaters]
133      updater-destroy
134      updater-life
135      updater-rotate
136    end
137
138  end
139
140  bundle-basic --> bundle-fireworks
141
142  subgraph bundle-full [tsParticles]
143
144    subgraph full-interactions [Interactions]
145
146      subgraph full-interactions-external [Externals]
147        interaction-external-trail[Trail]
148      end
149
150    end
151
152    subgraph full-plugins [Plugins]
153      plugin-absorbers[Absorbers]
154      plugin-emitters[Emitters]
155
156      subgraph full-plugin-emitters-shapes [Emitters Shapes]
157        plugin-emitters-shape-circle[Circle]
158        plugin-emitters-shape-square[Square]
159      end
160
161    end
162
163    subgraph full-shapes [Shapes]
164      shape-text[Text]
165    end
166
167    subgraph full-updaters [Updaters]
168      updater-destroy[Destroy]
169      updater-roll[Roll]
170      updater-tilt[Tilt]
171      updater-twinkle[Twinkle]
172      updater-wobble[Wobble]
173    end
174
175  end
176
177  bundle-slim --> bundle-full
178
179  subgraph bundle-all [tsParticles All]
180
181    bundle-pjs[tsParticles Particles.js Compatibility]
182
183    subgraph all-effects [Effects]
184      effect-bubble[Bubble]
185      effect-trail[Trail]
186    end
187
188    subgraph all-interactions [Interactions]
189      subgraph all-interactions-external [External]
190        interaction-external-particle[Particle]
191        interaction-external-pop[Pop]
192      end
193
194      interaction-light[Light]
195
196      subgraph all-interactions-particles [Particles]
197        interaction-particles-repulse[Repulse]
198      end
199    end
200
201    subgraph all-paths [Paths]
202      path-curl-noise[Curl Noise]
203      path-curves[Curves]
204      path-perlin-noise[Perlin Noise]
205      path-polygon[Polygon]
206      path-simplex-noise[Simplex Noise]
207      path-svg[SVG]
208    end
209
210    subgraph all-plugins [Plugins]
211      plugin-canvas-mask[Canvas Mask]
212
213      subgraph all-plugins-easings [Easings]
214        plugin-easing-back[Back]
215        plugin-easing-circ[Circ]
216        plugin-easing-cubic[Cubic]
217        plugin-easing-expo[Expo]
218        plugin-easing-linear[Linear]
219        plugin-easing-quart[Quart]
220        plugin-easing-quint[Quint]
221        plugin-easing-sine[Sine]
222      end
223
224      subgraph all-plugin-emitters-shapes [Emitters Shapes]
225        plugin-emitters-shape-canvas[Canvas]
226        plugin-emitters-shape-path[Path]
227        plugin-emitters-shape-polygon[Polygon]
228      end
229
230      subgraph all-plugins-exports [Exports]
231        plugin-export-image[Image]
232        plugin-export-json[JSON]
233        plugin-export-video[Video]
234      end
235
236      plugin-hsv-color[HSV Color]
237      plugin-infection[Infection]
238      plugin-motion[Motion]
239      plugin-poisson-disc[Poisson Disc]
240      plugin-polygon-mask[Polygon Mask]
241      plugin-sounds[Sounds]
242    end
243
244    subgraph all-shapes [Shapes]
245      shape-arrow[Arrow]
246      shape-cards[Cards]
247      shape-cog[Cog]
248      shape-heart[Heart]
249      shape-path[Path]
250      shape-rounded-polygon[Rounded Polygon]
251      shape-rounded-rect[Rounded Rect]
252      shape-spiral[Spiral]
253    end
254
255    subgraph all-updaters [Updaters]
256      updater-gradient[Gradient]
257      updater-orbit[Orbit]
258    end
259
260    simplex-noise --> path-curl-noise
261    perlin-noise --> path-perlin-noise
262    simplex-noise --> path-simplex-noise
263
264  end
265
266  bundle-full --> bundle-all

Sponsors

JetBrains

Huge thanks to JetBrains for the 2020-2022 Open Source Licenses!

JetBrains WebStorm is used to maintain this project.