Quickstart

This page assumes you’ve installed party.js. It takes you from a first burst of confetti to customizing and controlling effects.

Your first effect

Pass an element to confetti(), and confetti bursts out of it:

import { confetti } from "party-js";

const button = document.querySelector("#submit");
button.addEventListener("click", () => confetti(button));

Live Demo

Reduced motionPlay effects

Fire confetti

The confetti shoots out of the middle of the element, slows down quickly, and then flutters down like paper. The library draws it on a canvas over the page and removes the canvas again once the last piece is gone.

Customizing

Every effect takes an options object as its second argument. Options you leave out keep their default:

Live Demo

Reduced motionPlay effects

Fire more confetti

import { confetti, range } from "party-js";

confetti(button, {
    count: range(60, 90),
    spread: 100,
    startVelocity: range(1200, 2000),
});

Most options accept either a fixed value, like spread: 120, or a sampler, like range(80, 120), which picks a new random value each time it’s used. That’s what makes every burst look unique. Each option’s documentation says whether it’s picked once per burst or once per piece of confetti.

Colors work the same way. Pass a list of color strings and each piece picks one of them:

confetti(button, {
    colors: ["#ff5a5f", "#ffb400", "#00a699", "#7b61ff"],
});

Visit Confetti for more information on the effect.

Fire from a point

Instead of an element, you can pass a position in page coordinates, i.e. pixels from the top-left of the document. For example, to fire confetti wherever the user clicks:

area.addEventListener("click", (event) => {
    confetti({ x: event.pageX, y: event.pageY });
});

Live Demo

Reduced motionPlay effects

Fire from where you click

Sparkles

The other built-in effect is sparkles(). It works just like confetti(): it takes an element or a point, and an options object. Instead of confetti, it bursts small golden sparkles out in all directions, which twinkle and glint.

Live Demo

Reduced motionPlay effects

Sparkle

import { sparkles } from "party-js";

sparkles(button);

Visit Sparkles for more information on the effect.

Control a running effect

Effects start right away and clean up after themselves, so most of the time you can ignore what they return. When you need control, keep the returned effect:

const effect = confetti(button);

effect.pause(); // freezes the particles where they are
effect.resume(); // continues where it left off
effect.end(); // stops emitting, and lets the particles that are alive finish
effect.stop(); // removes the particles immediately
effect.finished; // a promise that resolves once the effect has ended

stop() is useful when the element the confetti belongs to goes away, for example when your component unmounts. end() matters for effects that emit particles continuously, like a custom stream: it turns them off gracefully, instead of making their particles vanish instantly.

Reduced motion

When a user has asked their system for reduced motion, party.js skips effects by default: nothing is drawn, and your code keeps running as if the effect had played. If your particles carry information the user shouldn’t miss, or the user explicitly asked for them, you can play them anyway:

confetti(button, { reducedMotion: "play" });

To change the default behavior for every effect, for example from a motion setting on your site, use setDefaultReducedMotion().

Next steps

• Effects describes each built-in effect and all its options.
• Samplers & randomness explains how values are picked, and which samplers there are.
• Custom effects shows how to build your own effect when the built-in ones aren’t enough.