Module tsParticles Engine - v3.3.0

banner

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 WhatsApp Telegram Reddit

tsParticles Product Hunt Buy Me A Coffee


Table of Contents


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

jsDelivr jsDelivr jsDelivr jsDelivr jsDelivr jsDelivr jsDelivr

cdnjs

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

npm npmjs

tsParticles Engine

npm npmjs

tsParticles Fireworks

npm npmjs

tsParticles Basic

npm npmjs

tsParticles Slim

npm npmjs

tsParticles

npm npmjs

tsParticles All

npm npmjs

npm install @tsparticles/engine

yarn

yarn add @tsparticles/engine

pnpm

pnpm install @tsparticles/engine

Import and require

const tsParticles = require("@tsparticles/engine");

// or

import { 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:

tsParticles demo tsParticles Confetti demo

index.html

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

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

app.js

// @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
/* tsParticles.load(@params); */

tsParticles
.load({
id: "tsparticles",
url: "presets/default.json",
})
.then((container) => {
console.log("callback - tsparticles config loaded");
})
.catch((error) => {
console.error(error);
});

//or

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

//or

tsParticles.load({
id: "tsparticles",
options: [
{
/* options here */
},
{
/* other options here */
},
],
});
//random object

tsParticles.load({
id: "tsparticles",
options: [
{
/* options here */
},
{
/* other options here */
},
],
index: 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

@tsparticles/angular

npm npm

Instructions available here

Astro

astro-particles

npm npm

Instructions available here

Ember.js

ember-tsparticles

npm npm

Instructions available here

Inferno

inferno-particles

npm npm

Instructions available here

jQuery

jquery-particles

npm npm

Instructions available here

Preact

preact-particles

npm npm

Instructions available here

ReactJS

@tsparticles/react

npm npm

Instructions available here

RiotJS

riot-particles

npm npm

You can find the instructions here

SolidJS

solid-particles

npm npm

You can find the instructions here

Svelte

@tsparticles/svelte

npm npm downloads

Instructions available here

VueJS 2.x

@tsparticles/vue2

npm npm

Instructions available here

VueJS 3.x

@tsparticles/vue3

npm npm

Instruction available here

Web Components

web-particles

npm npm

You can find the instructions here

WordPress

@tsparticles/wordpress

npm npm WordPress Plugin Downloads WordPress Plugin Active Installs

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.

Premium Addons for Elementor
Premium Addons for Elementor is one of the most common plugins for Elementor that offers more than 55 highly customizable Elementor Widgets and Section Add-ons. tsParticles is exclusively included in Premium Particles Section Add-on for 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 the need to write a single line of code. See a Live Example.

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

jsDelivr npmjs npmjs

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

demo

You can find the instructions here

Bubbles

jsDelivr npmjs npmjs

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

demo

You can find the instructions here

Confetti

jsDelivr npmjs npmjs

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

demo

You can find the instructions here

Fire

jsDelivr npmjs npmjs

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

demo

You can find the instructions here

Firefly

jsDelivr npmjs npmjs

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

demo

You can find the instructions here

Fireworks

jsDelivr npmjs npmjs

This preset loads a beautiful fireworks effect.

demo

You can find the instructions here

Fountain

jsDelivr npmjs npmjs

demo

You can find the instructions here

Links

jsDelivr npmjs npmjs

demo

You can find the instructions here

Sea Anemone

jsDelivr npmjs npmjs

demo

You can find the instructions here

Snow

jsDelivr npmjs npmjs

demo

You can find the instructions here

Stars

jsDelivr npmjs npmjs

demo

You can find the instructions here

Triangles

jsDelivr npmjs npmjs

demo

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

Particles demo


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

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


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.

tsParticles demo

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

$ pnpm i
$ pnpm run build
$ cd demo/vanilla
$ 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.

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.


Plugins/Customizations

tsParticles now supports some customizations 🥳.

You can create your own plugins

Read more here...


Dependency Graph

flowchart TD

subgraph core [Core]
engine[tsParticles Engine]
perlin-noise[Perlin Noise Lib]
simplex-noise[Simplex Noise Lib]
configs[tsParticles Configs]
end

subgraph bundle-basic [tsParticles Basic]

subgraph basic-movers [Movers]
move-base[Base]
end

subgraph basic-shapes [Shapes]
shape-circle[Circle]
end

subgraph basic-updates [Updaters]
updater-color[Color]
updater-opacity[Opacity]
updater-out-modes[Out Modes]
updater-size[Size]
end

end

engine --> bundle-basic

subgraph bundle-confetti [tsParticles Confetti]

subgraph confetti-plugins [Plugins]
plugin-emitters
plugin-motion
end

subgraph confetti-shapes [Shapes]
shape-cards
shape-emoji
shape-heart
shape-image
shape-polygon
shape-square
shape-star
end

subgraph confetti-updaters [Updaters]
updater-life
updater-roll
updater-rotate
updater-tilt
updater-wobble
end

end

bundle-basic --> bundle-confetti

subgraph bundle-slim [tsParticles Slim]

subgraph slim-interactions [Interactions]

subgraph slim-interactions-external [Externals]
interaction-external-attract[Attract]
interaction-external-bounce[Bounce]
interaction-external-bubble[Bubble]
interaction-external-connect[Connect]
interaction-external-grab[Grab]
interaction-external-pause[Pause]
interaction-external-push[Push]
interaction-external-remove[Remove]
interaction-external-repulse[Repulse]
interaction-external-slow[Slow]
end

subgraph slim-interactions-particles [Particles]
interaction-particles-attract[Attract]
interaction-particles-collisions[Collisions]
interaction-particles-links[Links]
end

end

subgraph slim-movers [Movers]
move-parallax[Parallax]
end

subgraph slim-plugins [Plugins]

subgraph slim-plugins-easings [Easings]
plugin-easing-quad[Quad]
end

end

subgraph slim-shapes [Shapes]
shape-emoji[Emoji]
shape-image[Image]
shape-line[Line]
shape-polygon[Polygon]
shape-square[Square]
shape-star[Star]
end

subgraph slim-updaters [Updaters]
updater-life[Life]
updater-rotate[Rotate]
updater-stroke-color[Stroke Color]
end

end

bundle-basic --> bundle-slim

subgraph bundle-fireworks [tsParticles Fireworks]

subgraph fireworks-effects [Effects]
effect-trail
end

subgraph fireworks-plugins [Plugins]
plugin-emitters

subgraph fireworks-plugin-emitters-shapes [Emitters Shapes]
plugin-emitters-shape-square
end

plugin-sounds
end

subgraph fireworks-updaters [Updaters]
updater-destroy
updater-life
updater-rotate
end

end

bundle-basic --> bundle-fireworks

subgraph bundle-full [tsParticles]

subgraph full-interactions [Interactions]

subgraph full-interactions-external [Externals]
interaction-external-trail[Trail]
end

end

subgraph full-plugins [Plugins]
plugin-absorbers[Absorbers]
plugin-emitters[Emitters]

subgraph full-plugin-emitters-shapes [Emitters Shapes]
plugin-emitters-shape-circle[Circle]
plugin-emitters-shape-square[Square]
end

end

subgraph full-shapes [Shapes]
shape-text[Text]
end

subgraph full-updaters [Updaters]
updater-destroy[Destroy]
updater-roll[Roll]
updater-tilt[Tilt]
updater-twinkle[Twinkle]
updater-wobble[Wobble]
end

end

bundle-slim --> bundle-full

subgraph bundle-all [tsParticles All]

bundle-pjs[tsParticles Particles.js Compatibility]

subgraph all-effects [Effects]
effect-bubble[Bubble]
effect-trail[Trail]
end

subgraph all-interactions [Interactions]
subgraph all-interactions-external [External]
interaction-external-particle[Particle]
interaction-external-pop[Pop]
end

interaction-light[Light]

subgraph all-interactions-particles [Particles]
interaction-particles-repulse[Repulse]
end
end

subgraph all-paths [Paths]
path-curl-noise[Curl Noise]
path-curves[Curves]
path-perlin-noise[Perlin Noise]
path-polygon[Polygon]
path-simplex-noise[Simplex Noise]
path-svg[SVG]
end

subgraph all-plugins [Plugins]
plugin-canvas-mask[Canvas Mask]

subgraph all-plugins-easings [Easings]
plugin-easing-back[Back]
plugin-easing-circ[Circ]
plugin-easing-cubic[Cubic]
plugin-easing-expo[Expo]
plugin-easing-linear[Linear]
plugin-easing-quart[Quart]
plugin-easing-quint[Quint]
plugin-easing-sine[Sine]
end

subgraph all-plugin-emitters-shapes [Emitters Shapes]
plugin-emitters-shape-canvas[Canvas]
plugin-emitters-shape-path[Path]
plugin-emitters-shape-polygon[Polygon]
end

subgraph all-plugins-exports [Exports]
plugin-export-image[Image]
plugin-export-json[JSON]
plugin-export-video[Video]
end

plugin-hsv-color[HSV Color]
plugin-infection[Infection]
plugin-motion[Motion]
plugin-poisson-disc[Poisson Disc]
plugin-polygon-mask[Polygon Mask]
plugin-sounds[Sounds]
end

subgraph all-shapes [Shapes]
shape-arrow[Arrow]
shape-cards[Cards]
shape-cog[Cog]
shape-heart[Heart]
shape-path[Path]
shape-rounded-polygon[Rounded Polygon]
shape-rounded-rect[Rounded Rect]
shape-spiral[Spiral]
end

subgraph all-updaters [Updaters]
updater-gradient[Gradient]
updater-orbit[Orbit]
end

simplex-noise --> path-curl-noise
perlin-noise --> path-perlin-noise
simplex-noise --> path-simplex-noise

end

bundle-full --> bundle-all

JetBrains JetBrains

Sponsors

JetBrains

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

JetBrains WebStorm is used to maintain this project.

Index

Modules

Core/Canvas Core/Container Core/Engine Core/Interfaces/Colors Core/Interfaces/IBounds Core/Interfaces/IBubbleParticleData Core/Interfaces/ICircleBouncer Core/Interfaces/IColorManager Core/Interfaces/IContainerInteractivity Core/Interfaces/IContainerPlugin Core/Interfaces/ICoordinates Core/Interfaces/IDelta Core/Interfaces/IDimension Core/Interfaces/IDistance Core/Interfaces/IDrawParticleParams Core/Interfaces/IEffectDrawer Core/Interfaces/IExternalInteractor Core/Interfaces/IInteractor Core/Interfaces/ILoadParams Core/Interfaces/IMouseData Core/Interfaces/IMovePathGenerator Core/Interfaces/IParticleColorStyle Core/Interfaces/IParticleHslAnimation Core/Interfaces/IParticleLife Core/Interfaces/IParticleMover Core/Interfaces/IParticleRetinaProps Core/Interfaces/IParticleRoll Core/Interfaces/IParticleTransformValues Core/Interfaces/IParticleUpdater Core/Interfaces/IParticleValueAnimation Core/Interfaces/IParticlesInteractor Core/Interfaces/IPlugin Core/Interfaces/IPositionFromSizeParams Core/Interfaces/IRangeValue Core/Interfaces/IRectSideResult Core/Interfaces/IShapeDrawData Core/Interfaces/IShapeDrawer Core/Interfaces/IShapeValues Core/Interfaces/ISlowParticleData Core/Interfaces/ITrailFillData Core/Particle Core/Particles Core/Retina Core/Utils/Constants Core/Utils/EventListeners Core/Utils/ExternalInteractorBase Core/Utils/InteractionManager Core/Utils/ParticlesInteractorBase Core/Utils/Point Core/Utils/QuadTree Core/Utils/Ranges Core/Utils/Vectors Enums/AnimationStatus Enums/Directions/MoveDirection Enums/Directions/OutModeDirection Enums/Directions/RotateDirection Enums/InteractivityDetect Enums/Modes/AnimationMode Enums/Modes/CollisionMode Enums/Modes/LimitMode Enums/Modes/OutMode Enums/Modes/PixelMode Enums/Modes/ResponsiveMode Enums/Modes/ThemeMode Enums/Types/AlterType Enums/Types/DestroyType Enums/Types/DivType Enums/Types/EasingType Enums/Types/EventType Enums/Types/GradientType Enums/Types/InteractorType Enums/Types/ParticleOutType Enums/Types/StartValueType Options/Classes/AnimatableColor Options/Classes/AnimationOptions Options/Classes/Background/Background Options/Classes/BackgroundMask/BackgroundMask Options/Classes/BackgroundMask/BackgroundMaskCover Options/Classes/ColorAnimation Options/Classes/FullScreen/FullScreen Options/Classes/HslAnimation Options/Classes/Interactivity/Events/ClickEvent Options/Classes/Interactivity/Events/DivEvent Options/Classes/Interactivity/Events/Events Options/Classes/Interactivity/Events/HoverEvent Options/Classes/Interactivity/Events/Parallax Options/Classes/Interactivity/Events/ResizeEvent Options/Classes/Interactivity/Interactivity Options/Classes/Interactivity/Modes/Modes Options/Classes/ManualParticle Options/Classes/Options Options/Classes/OptionsColor Options/Classes/Particles/Bounce/ParticlesBounce Options/Classes/Particles/Bounce/ParticlesBounceFactor Options/Classes/Particles/Collisions/Collisions Options/Classes/Particles/Collisions/CollisionsAbsorb Options/Classes/Particles/Collisions/CollisionsOverlap Options/Classes/Particles/Effect/Effect Options/Classes/Particles/Move/Move Options/Classes/Particles/Move/MoveAngle Options/Classes/Particles/Move/MoveAttract Options/Classes/Particles/Move/MoveCenter Options/Classes/Particles/Move/MoveGravity Options/Classes/Particles/Move/MoveTrail Options/Classes/Particles/Move/MoveTrailFill Options/Classes/Particles/Move/OutModes Options/Classes/Particles/Move/Path/MovePath Options/Classes/Particles/Move/Spin Options/Classes/Particles/Number/ParticlesDensity Options/Classes/Particles/Number/ParticlesNumber Options/Classes/Particles/Number/ParticlesNumberLimit Options/Classes/Particles/Opacity/Opacity Options/Classes/Particles/Opacity/OpacityAnimation Options/Classes/Particles/ParticlesOptions Options/Classes/Particles/Shadow Options/Classes/Particles/Shape/Shape Options/Classes/Particles/Size/Size Options/Classes/Particles/Size/SizeAnimation Options/Classes/Particles/Stroke Options/Classes/Particles/ZIndex/ZIndex Options/Classes/Responsive Options/Classes/Theme/Theme Options/Classes/Theme/ThemeDefault Options/Classes/ValueWithRandom Options/Interfaces/Background/IBackground Options/Interfaces/BackgroundMask/IBackgroundMask Options/Interfaces/BackgroundMask/IBackgroundMaskCover Options/Interfaces/FullScreen/IFullScreen Options/Interfaces/IAnimatable Options/Interfaces/IAnimatableColor Options/Interfaces/IAnimation Options/Interfaces/IColorAnimation Options/Interfaces/IHslAnimation Options/Interfaces/IManualParticle Options/Interfaces/IOptionLoader Options/Interfaces/IOptions Options/Interfaces/IOptionsColor Options/Interfaces/IResponsive Options/Interfaces/IValueWithRandom Options/Interfaces/Interactivity/Events/IClickEvent Options/Interfaces/Interactivity/Events/IDivEvent Options/Interfaces/Interactivity/Events/IEvents Options/Interfaces/Interactivity/Events/IHoverEvent Options/Interfaces/Interactivity/Events/IParallax Options/Interfaces/Interactivity/Events/IResizeEvent Options/Interfaces/Interactivity/IInteractivity Options/Interfaces/Interactivity/Modes/IModeDiv Options/Interfaces/Interactivity/Modes/IModes Options/Interfaces/Particles/Bounce/IParticlesBounce Options/Interfaces/Particles/Collisions/ICollisions Options/Interfaces/Particles/Collisions/ICollisionsAbsorb Options/Interfaces/Particles/Collisions/ICollisionsOverlap Options/Interfaces/Particles/Effect/IEffect Options/Interfaces/Particles/IParticlesOptions Options/Interfaces/Particles/IShadow Options/Interfaces/Particles/IStroke Options/Interfaces/Particles/Move/IMove Options/Interfaces/Particles/Move/IMoveAngle Options/Interfaces/Particles/Move/IMoveAttract Options/Interfaces/Particles/Move/IMoveCenter Options/Interfaces/Particles/Move/IMoveGravity Options/Interfaces/Particles/Move/IMoveTrail Options/Interfaces/Particles/Move/IMoveTrailFill Options/Interfaces/Particles/Move/IOutModes Options/Interfaces/Particles/Move/ISpin Options/Interfaces/Particles/Move/Path/IMovePath Options/Interfaces/Particles/Number/IParticlesDensity Options/Interfaces/Particles/Number/IParticlesNumber Options/Interfaces/Particles/Number/IParticlesNumberLimit Options/Interfaces/Particles/Opacity/IOpacity Options/Interfaces/Particles/Opacity/IOpacityAnimation Options/Interfaces/Particles/Shape/IShape Options/Interfaces/Particles/Size/ISize Options/Interfaces/Particles/Size/ISizeAnimation Options/Interfaces/Particles/ZIndex/IZIndex Options/Interfaces/Theme/ITheme Options/Interfaces/Theme/IThemeDefault Types/CustomEventArgs Types/CustomEventListener Types/ExportResult Types/ISourceOptions Types/ParticlesGroups Types/PathOptions Types/RangeType Types/RangeValue Types/RecursivePartial Types/ShapeData Types/SingleOrMultiple Utils/CanvasUtils Utils/ColorUtils Utils/EventDispatcher Utils/HslColorManager Utils/NumberUtils Utils/OptionsUtils Utils/RgbColorManager Utils/TypeUtils Utils/Utils bundle export-types exports index init