Have you seen particles effect in some websites and you want one too?
Do you have particles.js installed but it have problems or it's too heavy for your users?
Are you searching a new animation for your website?
Well, you are in the right place. tsParticles is a new library, started from the particles.js codebase, to have some particles animations in your website.
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
You should have opened a page like the one above, click on the latest release link if you need more informations or just click the tsparticles.min.js file to view it and you can download it.
You can place it anywhere in your website.
For example you can use a js folder, add the file there and create the script tag like this:
<!-- first include tsParticles --><scriptsrc="https://cdn.jsdelivr.net/npm/tsparticles@1.12.7/dist/tsparticles.min.js"></script><!-- then include jquery wrapper --><scriptsrc="https://cdn.jsdelivr.net/npm/jquery-particles@1.12.7/dist/jquery.particles.min.js"></script>
How to use
HTML
<divid="tsparticles"></div>
$("#tsparticles").particles().init({/* params */},function(container){// container is the particles container where you can play/pause or stop/start.// the container is already started, you don't need to start it manually.});// or$("#tsparticles").particles().ajax("particles.json",function(container){// container is the particles container where
First of all you need to find the tsparticles.min.js downloaded with the instructions above.
Once you are ready with the script tag included you have two option to start using tsParticles.
Javascript Object
You can use a Javascript object containing all options like this
letoptions={/* omitted for brevity, I'll describe the options later */};tsParticles.load('<element id>',options);//<element id> is a placeholder sample, use it without <>
External Json File
Otherwise you can use an external JSON file, it's easier to maintain because you need to change only this file and not your scripts that could be minified or something like that.
The JSON file is loaded like this
particles.json
{// omitted for brevity, I'll describe all the options later}
app.js
tsParticles.loadJSON('<element id>','particles.json');//<element id> is a placeholder sample, use it without <>
Particles Manager object
load and loadJSON methods returns a Promise<Container> object, the Container object is the object containing the canvas, the particles and all is needed to work.
You can access it using the method tsParticles.dom() which returns a Container[] with all containers initialized or tsParticles.domItem(index) which returns the specified Container if found, index is the array index, just a managed version of tsParticles.dom()[index].
If you want to unwrap the Promise you can await the load methods if you are using an async function or use the then method (Official API here).
Let's see a sample of then method:
app.js
tsParticles.load('<element id>',{/* omitted for brevity */}).then(function (container){// container is ready to be used});
The container object is really useful if you want to make particles more interactive or customizable.
Properties
options: The current options loaded in the object, some changes to this object can be effective only after a refresh()
Methods
play(force): Starts the animations or resume from pause, force is an optional boolean parameter to force the animation. This method doesn't allocate resources, just plays the animations.
pause(): Pauses the animations. This method doesn't clean any resource, just pauses the animations.
start(): Starts the container, reallocates all the resources freed by stop. Can't start after destroy.
stop(): Stops the container, frees unneeded resources.
destroy(): Destroys the container and invalidates it. The container will be unusable after this, any method called on it can return an error.
refresh(): This methods is a shorthand of stop/start cycle. This method is good to reload options changed by code.
exportImage(callback, type, quality): Exports the current canvas image, background property of options won't be rendered because it's css related. The callback is a function that handles the exported image, type is the image type you want to export and quality the quality of the image, these two parameters are optional.
exportConfiguration(): Exports the current configuration using options property returning a JSON string representing the options object.
draw(): Draws a single frame of animation, if you want to handle it yourself just pause the container and call draw when you need it.
getAnimationStatus(): Returns a boolean with the animation status, true is playing, false is paused
setNoise(noise): Customize noise generation with a noise object (three functions: generate, init, update)
setNoise(generator, init, update): Customize noise generation with a noise object destructured. The generator is a function taking a particle object and returning a noise value object (two properties: angle and length) that will be applied to particle movement. The init function is called in start method. The update function is called after all particles has been moved.
We can see that everything is disabled except the retina screen detection and the pause on window blur. So if you specify an empty config you'll have 100 unlinked particles that are not moving and without any interaction.
A little note, the black background is set by css because particles are white by default.
We can start with a config where particles are moving
