tsParticles - Easily create highly customizable JavaScript particles effect...



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
GitHub Sponsors jsDelivr hits (npm) Cdnjs npm npm lerna CodeFactor Codacy Badge Rate this package Gitpod Ready-to-Code Run on Repl.it
Discord Slack Telegram Reddit
[![tsParticles Product Hunt](https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=186113&theme=light)](https://www.producthunt.com/posts/tsparticles?utm_source=badge-featured&utm_medium=badge&utm_souce=badge-tsparticles") [![Buy Me A Coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20beer&emoji=🍺&slug=matteobruni&button_colour=5F7FFF&font_colour=ffffff&font_family=Arial&outline_colour=000000&coffee_colour=FFDD00")](https://www.buymeacoffee.com/matteobruni) Linktree

Table of Contents

⚠️⚠️ \_This readme refers to v2
version, read here forv1 documentation\* ⚠️⚠️

    -   Library installation
    -   Angular
    -   Inferno
    -   jQuery
    -   Preact
    -   ReactJS
    -   RiotJS
    -   SolidJS
    -   Svelte
    -   VueJS 2.x
    -   VueJS 3.x
    -   Web Components
    -   WordPress
    -   Elementor
-   Presets
    -   Big Circles
    -   Bubbles
    -   Confetti
    -   Fire
    -   Firefly
    -   Fireworks
    -   Fountain
    -   Links
    -   Sea Anemone
    -   Snow
    -   Stars
    -   Triangles
    -   Polygon mask
    -   Animated stars
-   Sponsors

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
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 jsDelivr jsDelivr





_tsParticles Engine_
npm npmjs

_tsParticles Slim_
npm npmjs

npm npmjs

  1. ``` sh
  2. npm install tsparticles-engine
  3. ```


  1. ``` sh
  2. yarn add tsparticles-engine
  3. ```


  1. ``` sh
  2. pnpm install tsparticles-engine
  3. ```

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

  1. ``` js
  2. const tsParticles = require("tsparticles-engine");

  3. // or

  4. import { tsParticles } from "tsparticles-engine";
  5. ```

The imported tsParticles is the same instance you have when including the script.




Load tsParticles and configure the particles:
tsParticles demo


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


  1. ``` js
  2. // @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
  3. /* tsParticles.loadJSON(@dom-id, @path-json, @callback (optional)); */

  4. tsParticles
  5.     .loadJSON("tsparticles", "presets/default.json")
  6.     .then(container => {
  7.         console.log("callback - tsparticles config loaded");
  8.     })
  9.     .catch(error => {
  10.         console.error(error);
  11.     });

  12. //or

  13. /* tsParticles.load(@dom-id, @options); */

  14. tsParticles.load("tsparticles", {
  15.     /* options here */
  16. });

  17. //or

  18. /* tsParticles.loadFromArray(@dom-id, @options, @index (optional)); */

  19. tsParticles.loadFromArray("tsparticles", [
  20.     {
  21.         /* options here */
  22.     },
  23.     {
  24.         /* other options here */
  25.     },
  26. ]);
  27. //random object

  28. tsParticles.loadFromArray(
  29.     "tsparticles",
  30.     [
  31.         {
  32.             /* options here */
  33.         },
  34.         {
  35.             /* other options here */
  36.         },
  37.     ],
  38.     1
  39. ); //the second one
  40. // Important! If the index is not in range 0...

  41. // after initialization this can be used.

  42. /* tsParticles.setOnClickHandler(@callback); */

  43. /* this will be fired from all particles loaded */

  44. tsParticles.setOnClickHandler((event, particles) => {
  45.     /* custom on click handler */
  46. });

  47. // now you can control the animations too, it's possible to pause and resume the animations
  48. // these methods don't change the config so you're safe with all your configurations
  49. // domItem(0) returns the first tsParticles instance loaded in the dom
  50. const particles = tsParticles.domItem(0);

  51. // play will start the animations, if the move is not enabled it won't enable it, it just updates the frame
  52. particles.play();

  53. // pause will stop the animations
  54. particles.pause();
  55. ```

Official components for some of the most used frameworks


npm npm

Instructions available here


npm npm

Instructions available here


npm npm

Instructions available here


npm npm

Instructions available here


npm npm

Instructions available here



npm npm

You can find the instructions here



npm npm

You can find the instructions here


npm npm downloads

Instructions available here

VueJS 2.x

npm npm

Instructions available here

VueJS 3.x

npm npm

Instruction available here

Web Components


npm npm

You can find the instructions here



npm npm WordPress Plugin Downloads WordPress Plugin Active Installs

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


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

Premium Addons for Elementor
Premium Addons for Elementor is one of the most common plugins for Elementor that offers 55+ highly customizable Elementor Widgets and Section Add-ons. tsParticles is exclusively included in the Premium Particles Section Add-on for the Elementor Page Builder. Check It Now.
Use Premium Addons for Elementor Page Builder and get the chance to include tsParticles in your next WordPress website without writing a single line of code. See a Live Example.


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

jsDelivr npmjs npmjs

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

You can find the instructions here


jsDelivr npmjs npmjs

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

You can find the instructions here


jsDelivr npmjs npmjs

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

You can find the instructions here


jsDelivr npmjs npmjs

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

You can find the instructions here


jsDelivr npmjs npmjs

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

You can find the instructions here


jsDelivr npmjs npmjs

This preset loads a beautiful fireworks effect.

You can find the instructions here


jsDelivr npmjs npmjs

You can find the instructions here


jsDelivr npmjs npmjs

You can find the instructions here

Sea Anemone

jsDelivr npmjs npmjs

You can find the instructions here


jsDelivr npmjs npmjs

You can find the instructions here


jsDelivr npmjs npmjs

You can find the instructions here


jsDelivr npmjs npmjs

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!

_Demo / Generator_

Particles demo

_Video Tutorials_

You can find all video tutorials on the website here:

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

Characters as particles

Particles chars demo

Polygon mask

tsParticles Polygon Mask demo

Animated stars

Particles NASA demo

Nyan cat flying on scrolling stars

Particles Nyan Cat demo

Snow particles

tsParticles Snow demo

Background Mask particles

tsParticles Background Mask demo


You can find some config samples here 📖


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

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

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

  1. ``` sh
  2. $ pnpm i
  3. $ npx lerna run build
  4. $ cd demo/vanilla
  5. $ pnpm run start
  6. ```

**Boom! 💥** 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.
jsDelivr npmjs npm

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


tsParticles now supports some customizations 🥳.

You can create your own plugins

_Read more here..._

Dependency Graphs

  1. ```mermaid
  2. flowchart TD

  3. subgraph c [Components]
  4. ca[Angular]
  5. ci[Inferno.js]
  6. cj[JQuery]
  7. cp[Preact]
  8. cre[React.js]
  9. cri[Riot.js]
  10. cso[Solid.js]
  11. csv[Svelte]
  12. cv2[Vue.js 2.x]
  13. cv3[Vue.js 3.x]
  14. cw[Web Components]
  15. end

  16. e[tsParticles Engine] --> c
  17. ```

  1. ```mermaid
  2. flowchart LR

  3. subgraph b [Bundles]
  4. bp[Particles.js compatibility bundle] --> bs[tsParticles Slim]
  5. bs --> bf[tsParticles]
  6. end

  7. e[tsParticles Engine] --> b

  8. iea & iebo & iebu & iec & ieg & iepa & iepu & ierem & ierep --> bs
  9. ipa & ipc & ipl --> bs
  10. mb & mp --> bs
  11. sc & si & sl & sp & ssq & sst & st --> bs
  12. ua & uc & ul & uop & uou & usi & ust --> bs

  13. iet --> bf
  14. pla & ple & plp --> bf
  15. ur & uti & utw & uw --> bf

  16. subgraph i [Interactions]

  17. subgraph ie [Externals]
  18. iea[Attract]
  19. iebo[Bounce]
  20. iebu[Bubble]
  21. iec[Connect]
  22. ieg[Grab]
  23. iepa[Pause]
  24. iepu[Push]
  25. ierem[Remove]
  26. ierep[Repulse]
  27. iet[Trail]
  28. end

  29. il[Light]

  30. subgraph ip [Particles]
  31. ipa[Attract]
  32. ipc[Collisions]
  33. ipl[Links]
  34. ipr[Repulse]
  35. end

  36. end

  37. i --> ie
  38. i --> ip

  39. e --> i

  40. subgraph m [Movers]
  41. mb[Base]
  42. mp[Parallax]
  43. end

  44. e --> m

  45. subgraph pa [Paths]
  46. pac[Curves]
  47. pape[Perlin Noise]
  48. papo[Polygon]
  49. pas[Simplex Noise]
  50. end

  51. e --> pa

  52. subgraph pl [Plugins]
  53. pla[Absorbers]
  54. ple[Emitters]
  55. pli[Infection]
  56. plp[Polygon Mask]
  57. end

  58. e --> pl

  59. subgraph s [Shapes]
  60. sb[Bubble]
  61. sc[Circle]
  62. sh[Heart]
  63. si[Image]
  64. sl[Line]
  65. sm[Multiline Text]
  66. sp[Polygon]
  67. sr[Rounded Rectangle]
  68. ssp[Spiral]
  69. ssq[Square]
  70. sst[Star]
  71. st[Text]
  72. end

  73. e --> s

  74. subgraph u [Updaters]
  75. ua[Angle]
  76. uc[Color]
  77. ug[Gradient]
  78. ul[Life]
  79. uop[Opacity]
  80. uor[Orbit]
  81. uou[Out Modes]
  82. ur[Roll]
  83. usi[Size]
  84. ust[Stroke Color]
  85. uti[Tilt]
  86. utw[Twinkle]
  87. uw[Wobble]
  88. end

  89. e --> u

  90. subgraph pr [Presets]
  91. prbi[Big Circles]
  92. prbu[Bubbles]
  93. prc[Confetti]
  94. prf[Fire]
  95. prff[Firefly]
  96. prfw[Fireworks]
  97. prfo[Fountain]
  98. prl[Links]
  99. prsa[Sea Anemone]
  100. prsn[Snow]
  101. prst[Stars]
  102. prt[Triangles]
  103. end

  104. e --> pr
  105. ```

JetBrains JetBrains

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

JetBrains WebStorm is used to maintain this project.



Codacy is a code quality platform that helps you to detect and fix code quality issues in your

Automate code reviews on your commits and pull requests

Check your code quality and keep track of your technical debt for more than 40 programming languages. Seamlessly
integrated within your development workflow.