Lightweight JS Library For Creating Interactive Particles – tsparticles

Preview:

Description:

tsparticles is an upgraded and continued version of the Particles.js library to create particles in an elegant way.

Rewritten in TypeScript and comes with a lot of new features:

• 12 pre-defined presets (JSON).
• Circle, line, edge, triangle, polygon, star shapes.
• Or using a custom image.
• More move out modes: bounce, bounce-vertical, and bounce-horizontal.
• Bugs fixed.
• And more customization options.
• Compatible with React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.

Install & Download:

# NPM
$ npm install tsparticles-engine --save

Basic usage (Vanilla JavaScript):

1. Import the tsparticles library.

// ES6+
import { tsParticles } from "tsparticles-engine";
// CommonJS
const tsParticles = require("tsparticles-engine");
// Browser
<script src="tsparticles.engine.min.js"></script>
// CDN
<script src="https://unpkg.com/tsparticles-engine/"></script>

2. Create a container where you want to render the particles.

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

3. Import a preset of your choice. Available presets:

• Big Circles
• Bubbles
• Confetti
• Fire
• Firefly
• Fireworks
• Fountain
• Links
• Sea Anemone
• Snow
• Stars
• Triangles

<script src="https://cdn.jsdelivr.net/npm/tsparticles-preset-big-circles@2/tsparticles.preset.bigCircles.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/tsparticles-preset-bubbles@2/tsparticles.preset.bubbles.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/tsparticles-preset-confetti@2/tsparticles.preset.confetti.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/tsparticles-preset-fire@2/tsparticles.preset.fire.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/tsparticles-preset-firefly@2/tsparticles.preset.firefly.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/tsparticles-preset-fireworks@2/tsparticles.preset.fireworks.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/tsparticles-preset-fountain@2/tsparticles.preset.fountain.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/tsparticles-preset-links@2/tsparticles.preset.links.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/tsparticles-preset-sea-anemone@2/tsparticles.preset.seaAnemone.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/tsparticles-preset-snow@2/tsparticles.preset.snow.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/tsparticles-preset-stars@2/tsparticles.preset.stars.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/tsparticles-preset-triangles@2/tsparticles.preset.triangles.bundle.min.js"></script>

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

4. You can also create custom particles by passing the following options:

tsParticles.load("tsparticles", { 
  /**
   * More custom options for external plugins or customizations
   */
  [name: string]: unknown;
  /**
   * Sets if the animations should start automatically or manually
   */
  autoPlay: boolean;
  /**
   * Background options, these background options will be used to the canvas element, they are all CSS properties
   */
  background: IBackground;
  /**
   * Background Mask options, what's behind the canvas will become hidden and particles will uncover it
   */
  backgroundMask: IBackgroundMask;
  /**
   * Sets the animated background mode for particles canvas bringing it to the back
   * @deprecated use the new fullScreen instead
   */
  backgroundMode: RecursivePartial | boolean;
  /**
   * Enables the retina detection, if disabled the ratio used by canvas will be always 1 and not the device setting.
   */
  detectRetina: boolean;
  /**
   * The Particles effect duration in seconds, then the container will be destroyed
   */
  duration: RangeValue;
  /**
   * The FPS (Frame Per Second) limit applied to all particles animations.
   */
  fpsLimit: number;
  /**
   * The Frame Per Second limit applied to all particles animations.
   * @deprecated use the new fpsLimit instead
   */
  fps_limit: number;
  /**
   * Sets the animated background mode for particles canvas bringing it to the back
   */
  fullScreen: RecursivePartial | boolean;
  /**
   * The particles interaction options
   */
  interactivity: IInteractivity;
  /**
   * Particles inserted at load time with a specific position
   */
  manualParticles: IManualParticle[];
  /**
   * Handles user's preferences about motion
   */
  motion: IMotion;
  /**
   * The particles options
   */
  particles: IParticlesOptions;
  /**
   * Enables or disabled the animation on window blur
   */
  pauseOnBlur: boolean;
  /**
   * Enable or disabled the animation if the element is outside the viewport
   */
  pauseOnOutsideViewport: boolean;
  /**
   * This property will be used to add specified presets to the options
   */
  preset?: SingleOrMultiple;
  /**
   * This sets custom options based on canvas size
   */
  responsive: IResponsive[];
  /**
   * Enables the retina detection, if disabled the ratio used by canvas will be always 1 and not the device setting.
   * @deprecated use the new detectRetina instead
   */
  retina_detect: boolean;
  /**
   * Enables a smooth effect, by default it's disabled
   * When enabled the animation will speed up or slow down depending on fps
   * The [[fpsLimit]] field will be used as a reference for the animation speed
   * Some examples:
   *      - with a [[fpsLimit]] of 60 the animation will be twice faster on 120 fps devices
   *      - with a [[fpsLimit]] of 120 the animation will be twice slower on 60 fps devices
   * The animation will be always smooth, but the behavior could be affected by the user screen refresh rate
   * It's recommended to keep this disabled, be careful.
   */
  smooth: boolean;
  style: RecursivePartial;
  /**
   * User-defined themes that can be retrieved by the particles [[Container]]
   */
  themes: ITheme[];
  /**
   * The maximum layers used in the z-axis
   */
  zLayers: number;
});

4. Play & pause the animation.

particles.play();
particles.pause();

Changelog:

v3.8.1 (02/01/2025)

• Bugfixes

v3.8.0 (01/24/2025)

• Bugfixes

v3.7.0 (11/19/2024)

• Bugfixes
• added new named color plugin, and hex color in the engine

v3.6.0 (11/19/2024)

• Bugfixes
• added isNull function, more secure checks
• added padding options to emoji shape

v3.5.0 (07/01/2024)

• added infinity shape
• bugfixes

v3.4.0 (05/13/2024)

• added infinity shape
• changed bundles loading method, no more preloading plugins
• fixed bugs

v3.3.0 (02/27/2024)

• fixed issues in Chrome with async rAF function, reduced async methods for vite builds

v3.2.0 (02/20/2024)

• fixed circular deps detection and other issues with dynamic imports

v3.1.0 (01/14/2024)

• added mute/unmute functions to sound plugin for an easier control of the volume
• added new options for sounds plugin, autoPlay and icons.enable
• added new zig-zag path
• added poisson disc plugin for better particles initial positions
• improved first pointerdown/touchstart event listener for better autoplay
• fixed bugs

v3.0.2 (12/06/2023)

• Added new EventType particleDestroyed
• Replaced text shape with emoji shape in @tsparticles/confetti
• Reworked @tsparticles/fireworks a bit for better output with the new v3 trails
• Bug Fixes

v3.0.0 (12/05/2023)

• Removed all tsParticles load methods to keep only a single one using a single object parameter.
• Removed support for shape deprecated properties like shape.image, shape.polygon, shape.stroke.
• Stroke now is a single object only like all the other particles properties.
• Removed multiline text shape, the text shape now supports that.
• Simplified some functions, using objects or removing unused overloads, this is breaking for v2 shapes.
• Moved some properties to private since they were public by mistake (this shouldn’t affect many, the properties were mainly used in the engine).
• Removed obsolete random properties in options objects.
• Removed emitters shapes from the plugin files, every emitters shape now has a dedicated package.
• All the components for Front End frameworks were removed from this repository, each one now has its own repository. This is mainly for maintainability. It’s easier to support multiple Front End frameworks versions in a dedicated repository instead of a multipurpose monorepository. Vue.js 2.x and 3.x were kept split because they have many differences.
• Removed all presets from this repository for a single one (https://github.com/tsparticles/presets) in the @tsparticles organization, this will make easier to contribute to specific presets or create new ones.
• All the previous packages will be deprecated when v3 will come out. Using only the new naming system is the main focus of v3. All the official packages will have @tsparticles/ organization in the package name, replacing tsparticles- prefix, except for tsparticles package which will remain the same.
• Pjs package now supports all the legacy pjs options only. This will make this package a wrapper for old pjs users. You can’t use tsParticles options in pjs calls.
• Pjs package is no longer part of @tsparticles/slim bundle, only included in @tsparticles/all.
• Text shape is no longer part of @tsparticles/slim bundle, included in tsparticles.
• Emoji shape is now part of @tsparticles/slim bundle.
• Added event on config added to the engine.
• Added flat options to tsparticles-confetti options.
• Creating support for effects, like bubble that wasn’t a real shape.
• Added linear easing.
  Created new emitters shapes: Canvas, Path and Polygon.
• Created trail effect plugin, this one is a real trail drawn in the canvas, it works also in transparent backgrounds. It requires more resources since it’s drawn calculating last N positions and not redrawing a semi-transparent canvas on itself, supports also fade.
• Added pop click interaction.
• Added limit mode (breaking changes on limit options).
• Added possibility to replace color and opacity for emitters shapes.
• Added more options for customizing noises values (only Simplex and Perlin paths).
• Added curl noise path plugin.
• Created Simplex and Perlin noise packages from their path plugins, they can be used in multiple packages without duplication (Curl Noise path for example).
• Added new emoji shape, better performance than text shape.
• Added clear flag to the root object, enabled by default, if disabled, the canvas won’t be cleared.
• Improved resize event and density formula

v2.8.0 (01/18/2023)

• Reworked move.trail options, created an object with color and image
• Bugfixes

v2.5.1 (11/03/2022)

• Fixed issue with ES modules

v2.4.0 (10/30/2022)

• Added reset method to updaters, this method will be called after a particle loses a life.
• Created the motion plugin for handling motion sickness, I moved this feature from the engine to a plugin since I prefer to have it more customizable. Everyone now can create their own motion sickness plugin, instead of having a standard behavior for everyone
• Added mutation observer to avoid style changes to the canvas when the fullScreen option is enabled (default behavior)
• Moved all easing functions to plugin packages, slim now depends on easing-quad since it’s the default value used in repulse and attract
• Added support for multiline text in canvas mask text options, separator and spacing are customizable values
• Added aria-hidden=”true” to canvas element
• Removed all canvas context save/restore calls, this should be a huge improvement to general performances
• Added the particles pool for reusing destroyed particles, every tsParticles instance will have its own pool
• Changed collision absorb code, added absorb.speed option to collisions section
• Added delay to root options
• Bug Fixes
• Refactored plugins to avoid passing options in init functions since it’s no more necessary
• Removed initAsync function from plugins, standard init is now async for all plugins
• Removed polygon mask plugin from the tsparticles package, this is a breaking change only for those that are using it. Since it’s a heavy plugin and not so much used, I have preferred removing it from the tsparticles package.
• Changed tsconfig target from es6 to es2019 (less transpilation to a reasonable target). The compatibility is still very high, reducing the bundle size.

v2.3.1 (09/15/2022)

• Added bounds to particles.destroy options, if the particle is outside one of the bounds the particle will be destroyed
• Added smooth to the options, it uses the fpsLimit field as a reference value trying to create a smoother animation on the provided fps value.
• Added canvasMask plugin, it uses a canvas, an image or a text for positioning particles in the canvas
• Moved out all the external interactors from the engine
• Removed support for very old browsers that don’t support requestAnimationFrame
• Bug Fixes

v2.2.2 (08/17/2022)

• Fixed double mouse events on mobile using pointer events

v2.2.1 (08/14/2022)

• Update to v2+

v1.42.5 (04/06/2022)

• Bug Fixes
• Compatibility changes

v1.42.4 (03/21/2022)

• Bugs fixed

v1.42.3 (03/19/2022)

• Bugs fixed

v1.42.1 (03/11/2022)

• Options Updates

v1.41.6 (03/03/2022)

• Fixed issue with canvas resize

v1.41.5 (02/25/2022)

• Fixed emitters issues, some presets were broken

v1.41.4 (02/20/2022)

• Removed useless console.log (debug purposes)

v1.41.3 (02/20/2022)

• Async Interactors
• Bugfixes

v1.41.0 (02/12/2022)

• Refactored path plugins to be more compatible with the new instance hierarchy
• Added more options to path plugins
• Updated ng-particles to Angular 13
• Bugfixes

v1.41.0 (02/11/2022)

• Static classes are replaced by Engine instance singletons, this is useful for multiple instances installations since they can behave differently
• Updated all packages to match the minor version, so it’s easier to understand which package is matching the engine version
• Added domId property to Emitters options, setting that to match a real dom element id will attach the emitter to the element
• The new instance singleton management is going to break the deprecated react-particles-js, but I decided to not change the major version since all the official components will continue to work as expected.

v1.39.3 (02/11/2022)

• updated fps limit default value to 120, updated all presets to have the fps limit of 120 (Chrome supports that also in Mac Pro Motion displays, Safari for now is limited to 60)
• Solved performance drop issue after the refresh

v1.39.2 (01/29/2022)

• Fixed editor issues

v1.39.1 (01/28/2022)

• Fixed issues with absorbers and emitters plugins Container extension methods

v1.39.0 (01/15/2022)

• Added all files for supporting the smaller engine file, preparing for v2 incoming changes. The engine file can be included or imported for a clean setup, and the plugins can be chosen manually
• Renamed Main class to Engine, kept backward compatibility
• Improved image loading, now they are loaded in parallel, and now if an image is missing, it will be loaded at runtime
  Breaking Changes
• Enums are not exported anymore, this breaks their javascript usages
• Fixed bugs

v1.38.0 (12/30/2021)

• Removed the custom canvas class (tsparticles-canvas-el), replacing it with a data attribute. This will break some CSS, but I’d prefer breaking it for focusing more on options
• Added style options, they are applied directly to the canvas, it’s the same .style object of the standard JavaScript HTMLElement class

v1.33.1 (07/30/2021)

• Fixed frozen frames (more than 1 second), this will fix the issue with pause on blur
• Removed some console.log calls

v1.32.0 (07/22/2021)

• Removed some old unused alias types
• Removed the infection plugin from the library, it’s an external plugin now
• Removed light interaction from the core library, it’s an external plugin now
• Bug Fixes
• Improved roll back color, now darken and enlighten can be set both and one of them will be picked randomly for each particle and will work also for animated colors
• Added particles orbits external plugin
• Added particle repulse external plugin

v1.31.1 (07/11/2021)

• improved images loading

v1.31.0 (07/10/2021)

• Added zIndex options
• Added particles groups to options
• Infection is now a plugin, and it’s included and is not included in the slim version
• Changed particles move distance options to an horizontal/vertical object, single number still valid

v1.30.0 (06/29/2021)

• Added wobble effect to particles, configurable in options
• Added tilt effect to particles, configurable in options
• Added roll options to particles, configurable in options
• Added all new sections to editor
• Bug Fixes

v1.29.0 (06/18/2021)

• Update

v1.28.0 (06/13/2021)

• Update

v1.18.0 (10/05/2020)

• Manual Particles
• Links and Triangles frequency
• Mouse hover can act as a light source
• Particles duplicates can be reduced
• Options have now a dedicated GUI editor library
• Theming options
• Added support to HSV colors
• OutMode can be configured for every canvas edge
• Bounce interaction mode; divs and mouse hover have this mode
• Particles can have a max radius to move inside
• Particles movement can be affected by the size, the higher the size, the higher the speed
• Particles movement has now gravity options
• Particles can have a custom life span and a life count, like the emitter options
• Particles can now configure bounces on canvas edge and for particles collisions
• New Motion settings for prefer-reduced-motion users, it can reduce or disable animations
• Single exported options type, used by all components
• Fixed click bubble mode
• Color animation with sync false in 1.17.0 used a random color instead of a random speed. This is fixed in 1.18.0 but you need to use the random value in color and not sync: false to achieve the same effect.

v1.17.9 (07/22/2020)

• Update

v1.17.2 (07/22/2020)

• Update

v1.17.1 (07/17/2020)

• Created InfernoJS component, inferno-particles
• Improved ReactJS and Preact components
• Fixed particle options override without shape type, now uses the main config shape type
• Added current pixel ratio parameter to ShapeDrawers draw and afterEffect functions
• Fixed stroke line width with pixel ratio
• Fixed Spiral shape plugin, using pixel ratio for calculating it’s shape

v1.17.0 (07/15/2020)

• Added path property to particles.rotate options to rotate the particle following its path, defaults to false
• Added trail mode for mouse interactivity (click and hover) to create a particle trail while moving or dragging the mouse
• Added attract click/hover mode to attract particles to mouse position
• Added draggable option to absorbers to make them draggable, defaults to false
• Fixed color un-sync animation start value
• Stroke color can now be animated like the (fill) color
• setOnClickHandler function has an additional parameter containing clicked particles

v1.16.0 (06/19/2020)

• Added bubble mode to div events
• Added type for div events, circle or rectangle are the values, it represent the div shape
• Renamed elementId property in onDiv object to ids
• div events now are more configurable, the onDiv property accepts a single object or an array of that object and the divEvent object supports ids property with single string or an array of strings
• bubble and repulse modes have a new divs property which is a similar object (or an array of it), it has ids (string or array) instead of divs for configure custom configuration for each div.
• particles move has a new property angle (degrees value) to configure the width of spread when it’s not set to straight: true and random: false. Defaults to 90 which is the previous behaviour.
• Two new collisions modes: absorb and destroy, the first merges two particles, the second one destroys the smaller one, if equal they will be destroyed both.
• detectRetina is now true by default
• noise is now a simpler object: only delay object and enable property are kept. Other properties have been removed for external noise management. You can now specify your own noise using the method setNoise on particles container.

v1.15.0 (05/31/2020)

• Interactivity grab mode now has a line color option
• Particles and link lines have a warp option, Particles will maintain the same coordinates in out mode and lines will link beyond canvas borders
• Particles color now has an animation section like the one on angle, opacity and size. It will animate the particles color.
• Added click mode pause to play/pause animations when the click event occurs.
• Added triangles options to links to fill the triangles between lines, color and opacity customizable
• Added id propery to links to create links between particles with the same id
• PolygonMask now has a new property data to work with, where you can specify a string with the SVG to use (well formatted, namespaces included) or an object with paths (array or single string, just the data, not the tag) and size
• Renamed lineLinked in links in particles, interactivity.modes.connect and interactivity.modes.grab, it’s still supported the old syntax
• Container particles.addParticle now it’s an easier method, it has two parameters: position ({ x: 0, y: 0 } for example) and overrideOptions (the same object specified in particles options). This method will add a new particle in that position if not undefined and with that options if not undefined
• Fixed a bug with links color used in override options (emitters, custom particles, etc…)
• Improved bubble mode interoperability with other modes
• Star shape improved with new draw method and another additional option called inset to specify the inset length.

v1.14.3 (05/21/2020)

• Fixed replaceColor option for SVG images

v1.14.2 (05/16/2020)

• Fixed a console message in ImageDrawer

v1.14.1 (05/14/2020)

• Fixed shape customizations

v1.14.0 (05/11/2020)

• Particles can now be destroyed after a threshold size (bigger or lower it’s your choice)
• Particles can infect other particles with a new infection option
• Particles can now vibrate with a new vibrate option
• Particles can set noise on move options
• Created a slim file tsparticles.slim.js that doesn’t have PolygonMask, Emitters and Absorbers.
• Play/Pause behavior now will have a better behavior in startup
• The particles number limit can be more flexible with area density integration. If you specify a density the limit will be affected by that calculation, this will improve responsiveness.
• The particles number density will be more customizable, the code has a 1000 factor hard coded, now that value is customizable.

v1.13.9 (05/04/2020)

• bugs fixed

v1.13.8 (05/03/2020)

• update

v1.13.2 (04/26/2020)

• critical bugfix on shape override options

v1.13.0 (04/25/2020)

• bubble mode on mouse hover and on mouse click has now a color option to change the color when the event occurs
• shape types options can now override almost all particles options, using the same structure. Omitted options will be taken from the particles options.
• repulse mode now has a speed option to change the repulse speed. The default value is 1 but this value will be multiplied by 100 in code to not break old settings. If you want a lower speed use decimals.
• polygon options (Polygon Mask to be clear) have a new position option, this have a { x: 50, y: 50 } default value, to keep the old behavior. x and y values are percentages, not absolute values, calculated on canvas width.
• polygon now can use a SVG file with multiple paths, all of them will be used.
• emitter introduced. Now you can have one or more areas in the canvas that spawn particles.
• absorber introduced. Now you can have one or more areas in the canvas that absorb particles.
• particles.twinkle animation introduced. Now you can have twinkling particles and linked lines.
• Bugs fixed

v1.12.10 (04/12/2020)

• Bugs fixed

v1.12.8 (04/11/2020)

• Bugs fixed

v1.12.7 (04/07/2020)

• Bugs fixed

v1.12.0 (04/03/2020)

• Updated

v1.11.1 (03/29/2020)

• Updated

v1.11.0 (03/28/2020)

• Updated

v1.10.4 (03/21/2020)

• Updated

v1.10.2 (03/16/2020)

• fixed polygon shape option loading
• now you can control the animations

v1.9.2 (03/13/2020)

• hotfix

v1.9.0 (03/12/2020)

• adjusted background mask settings