Lightweight JS Library For Creating Interactive Particles – tsparticles

Category: Animation , Javascript , Recommended | July 22, 2020
Author: matteobruni
Views Total: 98 views
Official Page: Go to website
Last Update: July 22, 2020
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:

  • 16 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.

Install & Download:

# NPM
$ npm install tsparticles --save

How to use it:

1. Load the tsparticles library from a CDN.

<script src="https://cdn.jsdelivr.net/npm/tsparticles/dist/tsparticles.min.js"></script>

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

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

3. Initialize the tsparticles and load a preset of your choice as follows:

  • bubble.json
  • chars.json
  • collisions.json
  • connect.json
  • default.json
  • images.json
  • mask.json
  • nasa.json
  • nyancat.json
  • nyancat2.json
  • shadow.json
  • slow.json
  • snow.json
  • star.json
  • test.json
  • virus.json
tsParticles.loadJSON("tsparticles", "presets/bubble.json").then((container) => {
  console.log("callback");
}).catch((error) => {
  console.error(error);
});

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

tsParticles.load("tsparticles", { 
  /**
   * Background options, these background options will be used to the canvas element, they are all CSS properties
   */
  background: {

    /**
     * The background color used by the canvas element, string or object
     * For Example: '#ffffff', 'rgb(255, 255, 255)', 'hsl(0, 100%, 100%)', 'random'
     */
    color: string or object,

    /**
     * The background opacity
     */
    opacity: number,

    /**
     * The background image used by the canvas element, its value will be used to set CSS property background-image
     */
    image: string,

    /**
     * The background position, it's used by the CSS property background-position
     */
    position: string,

    /**
     * The background position, it's used by the CSS property background-repeat
     */
    repeat: string,

    /**
     * The background size, it's used by the CSS property background-size
     */
    size: string,

  },

  /**
   * Background Mask options, what's behind the canvas will become hidden and particles will uncover it
   */
  backgroundMask: {

    /**
     * The color to use as a canvas background to cover
     */
    cover: {
      color: string or object,
      opacity: 0-1,
    },

    /**
     * This settings enables the cover and the particles behavior as unveiling elements
     */
    enable: boolean,

  },

  /**
   * Enables the retina detection, if disabled the ratio used by canvas will be always 1 and not the device setting.
   */
  detectRetina: boolean,

  /**
   * The Frame Per Second limit applied to all particles animations.
   * @deprecated use the new fpsLimit instead
   */
  fps_limit: number,

  /**
   * The F(rame)P(er)S(econd) limit applied to all particles animations.
   */
  fpsLimit: number,

  /**
   * The infection options
   */
  infection: {

    /**
     * if the infection can be cured, bringing back the particle to its normal state
    */
    cure: boolean,

    /**
     * the "symptoms" delay, after how many seconds the infected particle change its state
    */
    delay: 1,
    enable: boolean,

    /**
     * how many particles are infected at startup
    */
    infections: 1.
    stages: array   

  },

  /**
   * The particles interaction options
   */
  interactivity: {
    "detect_on": "canvas", // "canvas", "window","parent"
    "events": {
      "onhover": {
        "enable": false,
        /* 
          "grab"
          "bubble"
          "repulse"
          "connect"
          ["grab", "bubble"]
        */
        "mode": "repulse"
      },
      "onclick": {
        "enable": true,
        /*
          "push"
          "remove"
          "bubble"
          "repulse"
          "pause"
          "emitter"
          "absorber"
        */
        "mode": "push"
      },
      "onDiv": {
        "enable": true,
        /*
          "bubble"
          "repulse"
        */
        "mode": "push",
        /*
          "circle"
          "rectangle"
        */
        "type": "rectangle",
        "ids": string or array
      },
      "resize": true
    },
    "modes": {
      "connect": {
        "distance": 400,
        "radius": 60,
        "lineLinked": {
          opacity: 0-1,
        }
      },
      "grab": {
        "distance": 400,
        "lineLinked": {
          "opacity": 0-1,
        }
      },
      "bubble": {
        "distance": 400,
        "duration": 2,
        "size": 40,
      },
      "push": {
        "quantity": 4
      },
      "remove": {
        "quantity": 4
      },
      "repulse": {
        "distance": 200,
        "duration": 0.4
      },
      "emitter": object / array,
      "absorber": object / array
    }
  },

  /**
   * The particles options
   */
  particles: {
    "color": {
      "value": "#ffffff"
    },
    "links": {
      "distance": 150,
      "id": string,
      "color": string or object,
      "opacity": 0-1,
      "width": 1.5
    },
    "move": {
      "enable": true,
      "speed": 12,
      /*
        "none"
        "top"
        "top-right"
        "right"
        "bottom-right"
        "bottom"
        "bottom-left"
        "left"
        "top-left"
      */
      "direction": "none",
      "random": false,
      "straight": false,
      /*
        "out"
        "destroy"
        "bounce"
        "bounce-vertical"
        "bounce-horizontal"
      */
      "out_mode": "out",
      "collisions": false,
      "trail": {
        "enable": true,
        "length": 10,
        "fillColor": object
      }
      "attract": {
        "enable": false,
        "rotateX": 600,
        "rotateY": 1200
      }
    }
    "rotate": {
      "value": 80,
      "random": true,
      "direction": "clockwise or counterclockwise"
      "animation": {
        "enable": true,
        "speed": 5,
        "sync": true
      }
    },
    "number": {
      "value": 80,
      "limit": 200,
      "density": {
        "enable": true,
        "area": 800
      }
    },
    "opacity": {
      "value": 0.5,
      "random": {
        "enable": true,
        "minimumValue": 10
      },
      "animation": {
        "enable": false,
        "speed": 1,
        "minimumValue": 0.1,
        "sync": false
      }
    },
    "shape": {
      /* "circle"
      "line"
      "edge"
      "triangle"
      "polygon"
      "star"
      "image"
      ["circle", "triangle", "image"]
      */
      "type": "circle", 
      "particles": {
        // Particles options here
      },
      "fill": true / false,
      "close": true / false,
      "image": {
        "src": "img/github.svg",
        "width": 100,
        "height": 100,
        "replaceColor": false
      },
      polygon: {
        sides: 5
      },
      star: {
        sides: 5, 
        inset: 2
      },
      character: {
        value: "*",
        font: "Verdana",
        style: "",
        weight: ""
      }
    },
    "size": {
      "value": 10,
      "random": {
        "enable": true,
        "minimumValue": 10
      },
      "animation": {
        "enable": false,
        "speed": 80,
        "minimumValue": 0.1,
        "sync": false
      }
    },
    "stroke": {
      "width": 2,
      "color": object
    },
    "twinkle": {
      "particles": {
        "enable": false,
        "color": object,
        "frequency": 0-1,
        "opacity": 0-1,
      },
      "lines": object
    },
  },

  /**
   * Enables or disabled the animation on window blur
   */
  pauseOnBlur: boolean,

  /**
   * This property will be used to add specified presets to the options
   */
  preset: string | string[],

});

5. Or load particles from an array.

tsParticles.loadFromArray("tsparticles", [{ /* options here */ }, { /* other options here */ }]);

6. Fire an event when all particles are loaded.

tsParticles.setOnClickHandler((e) => { 
  /* custom on click handler */ 
});

7. Control the animations.

const particles = tsParticles.domItem(0);
// play the animations
particles.play();
// pause the animations
particles.pause();

Changelog:

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