Nitrogen Pumpkin Mulch

    tsparticles-engine
    TypeScript icon, indicating that this package has built-in type declarations

    2.3.3 • Public • Published

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

    tsParticles Product Hunt Buy Me A Coffee


    Table of Contents

    ⚠️⚠️ _This readme refers to v2 version, read here for v1 documentation* ⚠️⚠️


    Do you want to use it on your website?

    Documentation and Development references here 📖

    This library is available on the two 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

    cdnjs

    Cdnjs

    unpkg

    https://unpkg.com/tsparticles-engine/ https://unpkg.com/tsparticles-slim/ https://unpkg.com/tsparticles/


    npm

    tsParticles Engine

    npm npmjs

    tsParticles Slim

    npm npmjs

    tsParticles

    npm npmjs

    npm install tsparticles-engine

    yarn

    yarn add tsparticles-engine

    pnpm

    pnpm install tsparticles-engine

    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

    const tsParticles = require("tsparticles-engine");
    
    // or
    
    import { tsParticles } from "tsparticles-engine";

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


    NuGet

    Nuget


    Usage

    Load tsParticles and configure the particles:

    tsParticles 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, the object from the array will be random selected
    /* tsParticles.loadJSON(@dom-id, @path-json, @callback (optional)); */
    
    tsParticles
      .loadJSON("tsparticles", "presets/default.json")
      .then((container) => {
        console.log("callback - tsparticles config loaded");
      })
      .catch((error) => {
        console.error(error);
      });
    
    //or
    
    /* tsParticles.load(@dom-id, @options); */
    
    tsParticles.load("tsparticles", {
      /* options here */
    });
    
    //or
    
    /* tsParticles.loadFromArray(@dom-id, @options, @index (optional)); */
    
    tsParticles.loadFromArray("tsparticles", [
      {
        /* options here */
      },
      {
        /* other options here */
      },
    ]);
    //random object
    
    tsParticles.loadFromArray(
      "tsparticles",
      [
        {
          /* options here */
        },
        {
          /* other options here */
        },
      ],
      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

    ng-particles

    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

    react-particles

    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

    svelte-particles

    npm npm downloads

    Instructions available here

    VueJS 2.x

    vue2-particles

    npm npm

    Instructions available here

    VueJS 3.x

    vue3-particles

    npm npm

    Instruction available here

    Web Components

    web-particles

    npm npm

    You can find the instructions here

    WordPress

    wordpress-particles

    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 have also 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 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 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 in 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 checkout my profile

    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 ever more demos? Clone the repository on your computer and follow these instructions

    $ pnpm i
    $ npx lerna run build
    $ cd demo/vanilla
    $ pnpm run start

    Boom! 💥 http://localhost:3000 and you can checkout 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 Graphs

    flowchart TD
    
    subgraph c [Components]
    ca[Angular]
    ci[Inferno.js]
    cj[JQuery]
    cp[Preact]
    cre[React.js]
    cri[Riot.js]
    cso[Solid.js]
    csv[Svelte]
    cv2[Vue.js 2.x]
    cv3[Vue.js 3.x]
    cw[Web Components]
    end
    
    e[tsParticles Engine] --> c
    
    flowchart LR
    
    subgraph b [Bundles]
    bp[Particles.js compatibility bundle] --> bs[tsParticles Slim]
    bs --> bf[tsParticles]
    end
    
    e[tsParticles Engine] --> b
    
    iea & iebo & iebu & iec & ieg & iepa & iepu & ierem & ierep --> bs
    ipa & ipc & ipl --> bs
    mb & mp --> bs
    sc & si & sl & sp & ssq & sst & st --> bs
    ua & uc & ul & uop & uou & usi & ust --> bs
    
    iet --> bf
    pla & ple & plp --> bf
    ur & uti & utw & uw --> bf
    
    subgraph i [Interactions]
    
    subgraph ie [Externals]
    iea[Attract]
    iebo[Bounce]
    iebu[Bubble]
    iec[Connect]
    ieg[Grab]
    iepa[Pause]
    iepu[Push]
    ierem[Remove]
    ierep[Repulse]
    iet[Trail]
    end
    
    il[Light]
    
    subgraph ip [Particles]
    ipa[Attract]
    ipc[Collisions]
    ipl[Links]
    ipr[Repulse]
    end
    
    end
    
    i --> ie
    i --> ip
    
    e --> i
    
    subgraph m [Movers]
    mb[Base]
    mp[Parallax]
    end
    
    e --> m
    
    subgraph pa [Paths]
    pac[Curves]
    pape[Perlin Noise]
    papo[Polygon]
    pas[Simplex Noise]
    end
    
    e --> pa
    
    subgraph pl [Plugins]
    pla[Absorbers]
    ple[Emitters]
    pli[Infection]
    plp[Polygon Mask]
    end
    
    e --> pl
    
    subgraph s [Shapes]
    sb[Bubble]
    sc[Circle]
    sh[Heart]
    si[Image]
    sl[Line]
    sm[Multiline Text]
    sp[Polygon]
    sr[Rounded Rectangle]
    ssp[Spiral]
    ssq[Square]
    sst[Star]
    st[Text]
    end
    
    e --> s
    
    subgraph u [Updaters]
    ua[Angle]
    uc[Color]
    ug[Gradient]
    ul[Life]
    uop[Opacity]
    uor[Orbit]
    uou[Out Modes]
    ur[Roll]
    usi[Size]
    ust[Stroke Color]
    uti[Tilt]
    utw[Twinkle]
    uw[Wobble]
    end
    
    e --> u
    
    subgraph pr [Presets]
    prbi[Big Circles]
    prbu[Bubbles]
    prc[Confetti]
    prf[Fire]
    prff[Firefly]
    prfw[Fireworks]
    prfo[Fountain]
    prl[Links]
    prsa[Sea Anemone]
    prsn[Snow]
    prst[Stars]
    prt[Triangles]
    end
    
    e --> pr
    

    JetBrains JetBrains

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

    JetBrains WebStorm is used to maintain this project.


    Sponsors

    Codacy

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

    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.

    Install

    npm i tsparticles-engine

    DownloadsWeekly Downloads

    13,735

    Version

    2.3.3

    License

    MIT

    Unpacked Size

    1.76 MB

    Total Files

    1013

    Last publish

    Collaborators

    • ar3s
    • matteobruni