tsParticles 3.0.0 is out. Breaking changes ahead.

tsParticles 3.0.0 Changelog (link)

tsparticles / tsparticles

tsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.

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

---

Table of Contents

• tsParticles - TypeScript Particles
  • Table of Contents
  • Do you want to use it on your website?
  • Library installation
    • Hosting / CDN
      • jsDelivr
      • cdnjs
      • unpkg
    • npm
    • yarn
    • pnpm
      • Import and require
    • Usage
  • Official components for some of the most used frameworks
    • Angular
      • ng-particles
    • Astro
      • astro-particles
    • Ember.js
      • ember-tsparticles
    • Inferno
      • inferno-particles
    • jQuery
      • jquery-particles
    • Preact
      • preact-particles
    • ReactJS
      • react-particles
    • RiotJS
      • riot-particles
    • SolidJS
      • solid-particles
    • Svelte
      • svelte-particles
    • VueJS 2.x
      • vue2-particles
    • VueJS 3.x
      • vue3-particles
    • Web Components
      • web-particles
    • WordPress
      • wordpress-particles
    • Elementor
  • Presets
    • Big Circles
    • Bubbles
    • Confetti
    • Fire
    • Firefly
    • Fireworks
    • Fountain
    • Links
    • Sea Anemone
    • Snow
    • Stars
    • Triangles
  • Templates and Resources
  • Demo / Generator
  • Video Tutorials
    • Characters as particles
    • Polygon mask
    • Animated stars
    • Nyan cat flying on scrolling stars
    • Snow particles
    • Background Mask particles
  • …

View on GitHub

Keep reading for more details about v3, they're after the changelog...

BREAKING CHANGES

• 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
  • the stroke property can be found in the particles section, not in the shape object
  • the image and polygon properties, like any other shape, are part of the shape.options object
• 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

Major Changes

• 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.
  • Angular (@tsparticles/angular): https://github.com/tsparticles/angular (v3 under development)
  • Astro (@tsparticles/astro): https://github.com/tsparticles/astro (v3 under development)
  • Ember (@tsparticles/ember): https://github.com/tsparticles/ember (v3 under development)
  • Inferno (@tsparticles/inferno): https://github.com/tsparticles/inferno (v3 under development)
  • jQuery (@tsparticles/jquery): https://github.com/tsparticles/jquery (v3 under development)
  • Lit (@tsparticles/lit): https://github.com/tsparticles/lit (v3 under development)
  • Preact (@tsparticles/preact): https://github.com/tsparticles/preact (v3 under development)
  • React (@tsparticles/react): https://github.com/tsparticles/react (v3 under development)
  • Riot (@tsparticles/riot): https://github.com/tsparticles/riot (v3 under development)
  • Solid (@tsparticles/solid): https://github.com/tsparticles/solid (v3 under development)
  • Svelte (@tsparticles/svelte): https://github.com/tsparticles/svelte (v3 under development)
  • Vue.js (@tsparticles/vue): https://github.com/tsparticles/vue (v3 under development)
  • Web Components (@tsparticles/webcomponents): https://github.com/tsparticles/webcomponents (v3 under development)
  • WordPress (@tsparticles/wordpress): https://github.com/tsparticles/wordpress (v3 under development)
• 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. (Renaming them to @tsparticles/preset-<name> #3977)
• 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.
• Moved editor to its own repository: https://github.com/tsparticles/editor
• 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.

New Features

• 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

Bug Fixes

• Improved resize event and density formula

---

How to migrate from v2 to v3?

Version 2.x is still the latest tag on npm, but the next version has a 3.0.0 version, which is something I need to release to the public to find issues, and receive some feedbacks.

As it can be seen in the changelog above, the packages are now renamed using the @tsparticles/ "grouping" on NPM. All future tsParticles official packages will be released there, except the main package.

Also from the changelog, there are breaking changes in the options and in the main load api. Many options were deprecated and keeping them kept the bundle size bigger.

The main load api is now a single function, there is no more loadJSON, set, setJSON in the tsParticles instance.

Now there's only tsParticles.load and it gets a new object, introduced in latest v2 versions.

The new tsParticles.load signature is this:

/* await */ tsParticles.load({
    // element: /* an HTML element used as container for the canvas, if a canvas is passed, is used that instead of a generated canvas, optional */
    // id: /* a string to identify the current loading instance, if not passed, a random id is generated */
    // index: /* a number used to choose from an item if the options are an array, optional, ignored if options is object */
    // options: /* the options of the instance, can be an array of options object, optional if url is passed, if none is passed it's meaningless to load anything */
    // url: /* the url used to load the options, uses AJAX to get the options object, the result is then used like the options object above. */
});

The component libraries for the most common frontend frameworks/libraries are still under development, but since the core library is ready to be released I decided to use the tag next again. Using v3 with v2 packages is not possible and not recommended, there are many breaking changes under the hood. If a v2 package can't be found in v3, it could've been renamed or removed because deprecated.

Important note on trails

One of the most requested feature was using trails in a transparent background, it is now possible with the new trail effect, but is an external package, I didn't want to include that package in any bundle except @tsparticles/all (which contains all packages) because it's something completely new. I don't want to increase the bundle size to others who are not using it.
It can be used like any other tsParticles plugin library importing it and loading it into the instance.

The old trails are still available, they're more performant since they are made covering with a semitransparent layer the canvas. It's a common performant solution, for transparent backgrounds the new trails are the only way.

Important note on emojis

Emojis in v1 and v2 could be used using the text shape. Now from v3 there's a new emoji shape, it's more performant since emoji don't care about font color. You can customize only the font family (I recommend keeping the default value, but who knows), and the value like in the text shape. The best result is with one emoji per string value. Use an array if more than one is needed.
The text shape is now part of the tsparticles package instead of @tsparticles/slim, the emoji shape is part of that package instead. This will make things easier, migrate to the emoji shape if using emojis, you'll notice the difference.

What's next?

After this, the v3 package will be updated as always, but the priority now are the component libraries. Any help is appreciated, as always.

How to see new v3 options?

The configs used for testing can be found here:

https://github.com/tsparticles/tsparticles/tree/main/utils/configs/src

They can be used like explained in the readme:

https://github.com/tsparticles/tsparticles/tree/main/utils/configs#usage

---

Have fun with particles, confetti and/or fireworks. Remember to share the project if you like it, and leave a star on GitHub

https://github.com/tsparticles/tsparticles