Lightweight JS Library For Creating Interactive Particles – tsparticles

Category: Animation , Javascript , Recommended | September 15, 2022
Author:matteobruni
Views Total:3 views
Official Page:Go to website
Last Update:September 15, 2022
License:MIT

Preview:

Lightweight JS Library For Creating Interactive Particles – tsparticles

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 popular frameworks: jQuery, Angular, React, Vue, etc.

Install & Download:

# NPM
$ npm install tsparticles-engine --save

How to use it (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/[email protected]/tsparticles.preset.bigCircles.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/tsparticles.preset.bubbles.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/tsparticles.preset.confetti.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/tsparticles.preset.fire.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/tsparticles.preset.firefly.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/tsparticles.preset.fireworks.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/tsparticles.preset.fountain.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/tsparticles.preset.links.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/tsparticles.preset.seaAnemone.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/tsparticles.preset.snow.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/tsparticles.preset.stars.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/tsparticles.preset.triangles.bundle.min.js"></script>
tsParticles.load("tsparticles", {
  preset: "bigCircles",
});

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;
});

Changelog:

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

You Might Be Interested In:


Leave a Reply