# party-js gives you a particle system for the DOM, and it measures the page only once

> party-js is a TypeScript library compiled to a UMD module that adds particle effects such as confetti to an HTML document. It has no runtime dependencies and ships a CDN build, but it sizes its container once and expects you to handle document resizing yourself.

**yiliansource/party-js** — A JavaScript library to brighten up your user's site experience with visual effects!

- Repository: https://github.com/yiliansource/party-js
- Website: https://party.js.org
- Stars: 1,024 · Forks: 49
- Language: TypeScript
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/yiliansource-party-js

## The library is a particle system that draws into the document

The project describes itself as a JavaScript library to brighten up your site's user experience with visual effects, and the implementation is more specific than that tagline suggests. It offers a customizable particle system implementation into HTML documents, and users are able to create and fine-tune effects to their liking. A few simple effects are available out of the box, so that you do not have to spend time re-creating simple effects. The repository topics line up with that description, listing emitters, javascript-library, particles, party and visual-effects. The library is written in TypeScript and compiled to a UMD module, which is the architectural decision that shapes everything else about how you consume it. The homepage party.js.org carries the documentation, and the quick start guide lives there rather than in the repository, so the README is deliberately short and points outward.

## Two ways in: a global party object from a CDN, or a package import

The distribution strategy is the first thing to sort out, and the library supports two distinct audiences. For browsers, you can grab the latest version from jsdelivr with a plain script tag, and the library instance is loaded into the global party object.

```html
<script src="https://cdn.jsdelivr.net/npm/party-js@latest/bundle/party.min.js"></script>
```

For a package-managed environment, the same library installs from npm, or through yarn.

```bash
npm install party-js
# or
yarn add party-js
```

To use it, you simply require or import it, and the two forms are shown side by side.

```ts
import party from "party-js";
// or
const party = require("party-js");
```

That dual path is a consequence of the UMD target rather than a special case. The package.json points main at ./lib/index.js, types at ./lib/index.d.ts and the exports map at the same index, and the dependencies object is empty, so nothing is pulled in at runtime. A site that wants one button effect can drop in a script tag without a build step, while an application that already has a bundler can treat it as an ordinary dependency.

## The quick start is one click handler and a variation range

The usage example in the README shows the shape of the API and the shape of a typical integration. A click listener on an element calls party.confetti with the element as the target and an options object, and the only option set is count, whose value comes from party.variation.range with a lower and upper bound.

```js
document.querySelector(".button").addEventListener("click", function (e) {
    party.confetti(this, {
        count: party.variation.range(20, 40),
    });
});
```

Two design points hide in those few lines. The first argument to confetti is the DOM element, so the effect is anchored to the thing that was clicked rather than to the centre of the viewport, and the options object is where tuning happens. The second is the variation helper, which exists so that a repeated effect does not look identical every time, since a fixed particle count and a fixed path would produce the same animation on every press. The library therefore treats randomness as a first class part of the API rather than something each caller has to wire up with a random function. The documentation for the quick start is at party.js.org/docs, and the fuller usage lives there as well.

## The container is measured once, so a resizing page cuts the particles off

The known issues section documents one behaviour in detail, and it is the most important thing to know before you ship this on a page that changes size. The symptom is that particles are getting cut off inside the screen. The cause is that when creating the particle container, the library calculates the document body's size once, and it does not do this on a per-frame basis, in order not to involuntarily slow down older devices with timeout polling, and because watching for document size changes is an expensive task as of writing. The documentation gives two ways out. You can remove the #party-js-container, which forces the library to re-initialize the container and re-calculate the size, with the note that all particles remain in memory so nothing is lost. Or you can manually calculate the needed container size and update it yourself. On a page whose height changes after a font loads or a panel expands, this is a decision you have to make explicitly rather than something the library handles.

## TypeScript in, UMD out, with webpack and terser doing the bundling

The build pipeline is worth understanding if you plan to fork or extend the library, because the output layout is what consumers actually depend on. The package.json scripts are clean, build, test, lint and dev. Build is a three step chain that cleans the bundle and lib directories with rimraf, runs the TypeScript compiler with tsc, and then bundles with webpack, and prepublishOnly runs the same build before publishing. Dev runs webpack serve, lint runs eslint across .js and .ts files, and test runs mocha with ts-node/register over the tests directory, using chai for assertions. The dependency tree explains the rest: typescript, ts-loader, webpack, webpack-cli and terser-webpack-plugin handle compilation and minification, while prettier with an import sorting plugin and eslint with the typescript-eslint parser handle style. The repository root holds the corresponding configuration, with .eslintrc.js, .prettierrc, .prettierignore, .eslintignore, tsconfig.json, webpack.config.js and a .npmignore, and the docs, samples, src and tests directories carry the sources, the example page and the test suite.

## A hand written canvas loop is the other route, and it costs more but answers to you

There is a genuine alternative to a particle library, and it is simply writing the animation yourself on a canvas element. The difference in approach is where the ownership sits. With party-js you get an emitter model, a variation helper for randomised results, a set of ready made effects and a container the library manages for you, and the trade is that you accept the library's assumptions, including the one-time body measurement and the #party-js-container element. Writing the loop yourself means you own the requestAnimationFrame cycle, the particle state, the resize handling and the cleanup, and you can make the effect respond to layout changes because the sizing is your code. The choice really comes down to how much of the effect you need to control. A one-off confetti burst on a signup button is exactly the case party.js covers, while a continuous background effect tied to scroll position or live data is not, and in that situation a bespoke canvas implementation or a CSS animation on the elements themselves is the more honest answer. The library's own samples directory, with an index.html, a script.js, a style.css and a banner.svg, shows the integration it is designed for.

## Published version from 2022, repository work continuing into 2026

The version history is a little unusual, and it is worth understanding before you pin a dependency. The recent releases listed for the project are v2.2.0 from 2022-07-11, v2.1.3 from 2022-06-07 and v2.1.2 from 2021-10-11, so the last published npm version is more than three years old at the time of writing, even though the package.json still declares version 2.2.0 and the repository has been pushed to recently, with the last push on 2026-10-14. The repository is not archived, so the code is not frozen, but the published artefact and the repository head are not the same thing here. A CHANGELOG.md is tracked at the root, and the project also keeps its documentation in a docs directory built by a separate workflow, with a docs status badge in the README. The licence is MIT, recorded in a LICENSE.md file, and the package keywords are party, confetti and particles.

## Conclusion

party-js suits a site that wants a celebratory effect on a button click and does not want to write a canvas animation loop itself, since the effects ship ready to use and the library carries no runtime dependencies. It is the wrong tool if your page changes size after load, because the container is measured once and the fix is manual, and it is the wrong tool if you need continuous background animation rather than a burst triggered by an event. Before you adopt it, check that the effects you want are among those it ships, and read the known issues section, because the container sizing behaviour affects every layout that resizes. The licence is MIT, the latest published version is 2.2.0 from 2022-07-11, and the last push to the repository was on 2026-10-14.

## FAQ

### How do I install party-js in a browser?

Load the UMD build from jsdelivr with a script tag pointing at https://cdn.jsdelivr.net/npm/party-js@latest/bundle/party.min.js. The library instance is then available as the global party object.

### How do I install party-js with npm?

Run npm install party-js, or yarn add party-js, then import it as a default import or require it. The package has no runtime dependencies and ships type declarations alongside the compiled output.

### Why are my party.js particles cut off at the screen edge?

The library calculates the document body size once when it creates the particle container and does not re-measure it per frame. Either remove the #party-js-container to force a re-initialisation, or calculate and update the container size yourself.

### What effects does party-js ship with?

The library offers a few simple effects out of the box so you do not have to re-create simple effects, and the confetti effect is the one shown in the usage example, triggered from a click handler with a count option.

## Sources

- [License: MIT](https://github.com/yiliansource/party-js/blob/main/LICENSE)
- [Project website](https://party.js.org)
- [README](https://github.com/yiliansource/party-js/blob/main/README.md)
- [Releases](https://github.com/yiliansource/party-js/releases)
- [yiliansource/party-js on GitHub](https://github.com/yiliansource/party-js)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/yiliansource-party-js