# konfeti 0.6.0: full documentation

> Zero-dependency, strictly typed, highly customizable canvas confetti with emoji, text, image and spritesheet particles. Version 0.6.0, MIT license, runs in the browser (ES2022).

Install with `npm install konfeti`. The everyday API is the shared `Konfeti` object: `Konfeti.fire(options?)`
fires one burst (or a list of bursts) on a fullscreen canvas and returns a handle. `KonfetiFactory.create()`
makes a dedicated instance (own canvas, defaults, particle budget), `createWorker()` from `konfeti/worker`
renders off the main thread, and `konfeti/lite` is the smallest entry (paper only until shapes are registered
with `registerShapes`, no presets). Every option is optional and typed; the API reference gives each option's
unit, range and default.

The guide comes first, then the API reference. Index of the separate pages: https://konfeti.mbattaloglu.com/llms.txt

---

# konfeti

Zero-dependency, strictly typed, highly customizable canvas confetti — with first-class **emoji, text, image
and spritesheet** particles, composable physics and a typed plugin API.

**English** · [Türkçe](https://konfeti.mbattaloglu.com/docs/tr.md)

**npm**

```sh
npm install konfeti
```

**pnpm**

```sh
pnpm add konfeti
```

**yarn**

```sh
yarn add konfeti
```

```ts
import { Konfeti } from "konfeti";

Konfeti.fire(); // classic confetti pop
```

## API at a glance

```ts
import {
  Konfeti, // the ready-made, shared instance: draws on a fullscreen overlay canvas
  KonfetiFactory, // builds extra instances on your own canvas (Web Worker: createWorker in konfeti/worker)
  KonfetiPresets, // ready-to-fire looks: SNOW, FIREWORKS, STARS …
  extendPreset, // a preset plus your own settings
  type FireOptions, // the type of every fire() setting, for autocomplete
} from "konfeti";

// ── the shared instance: nothing to set up ──
Konfeti.fire(); // one classic confetti pop, upward from just below the screen center
Konfeti.fire({ particleCount: 120, spread: 90, origin: { x: 0.5, y: 0.3 } }); // your own settings
Konfeti.fire(KonfetiPresets.SNOW); // a preset, as is
Konfeti.fire(extendPreset(KonfetiPresets.SNOW, { particleCount: 60 })); // a preset, tweaked

const burst = Konfeti.fire(); // every fire() returns a handle for that burst…
burst.pause(); // …freeze just this burst
burst.resume(); // …continue it
await burst; // …or wait until its last particle is gone

const trail = Konfeti.emit({ rate: 40, follow: "pointer" }); // a stream that follows the pointer…
trail.stop(); // …until you stop it

Konfeti.onClick(button, { particleCount: 30 }); // fire from the click position on every click
Konfeti.pause(); // freeze everything (e.g. while an ad is not visible)
Konfeti.resume(); // continue everything
Konfeti.reset(); // remove every particle at once

// ── your own instance: own canvas, own defaults, own particle limit ──
const stage = KonfetiFactory.create(canvas, { maxParticles: 800 });
stage.fire(); // same API as Konfeti, drawn on `canvas`
stage.destroy(); // stop, clear and remove its listeners when you are done

// ── typed options: every setting autocompletes and is checked ──
const options: FireOptions = { particleCount: 80, paper: { colors: ["#d6ff3f", "#ffffff"] } };
Konfeti.fire(options);
```

## Contents

- [API at a glance](#api-at-a-glance)
- [Basics](#basics)
- [The paper particle](#the-paper-particle)
- [Shapes](#shapes)
- [Physics](#physics)
- [Emission](#emission)
- [Continuous emitter](#continuous-emitter)
- [Formations](#formations)
- [Presets](#presets)
- [Hooks](#hooks)
- [Instances & canvases](#instances--canvases)
- [Worker rendering](#worker-rendering)
- [Playable ads & webviews](#playable-ads--webviews)
- [Custom shapes & physics](#custom-shapes--physics)
- [Bundle size & `konfeti/lite`](#bundle-size--konfetilite)
- [Units & ranges](#units--ranges)
- [AI assistants](#ai-assistants)

## Basics

```ts
import { Konfeti } from "konfeti";

const burst = Konfeti.fire({
  particleCount: 120,
  angle: 60, // 90 = up, 0 = right
  spread: 55,
  origin: { x: 0, y: 0.7 }, // normalized canvas position
});

burst.pause();
burst.resume();
await burst; // resolves when every particle is gone
```

`origin` can also be an **element** (particles start from its center) or a **click event**:

```ts
button.addEventListener("click", (event) => Konfeti.fire({ origin: event }));
Konfeti.fire({ origin: document.querySelector("#buy")! });
```

Every numeric option accepts a fixed value or a random **range**: `10`, `[8, 14]` or `{ min: 8, max: 14 }`.

Every handle reports its random **seed**. Fire the same options with it to get the same burst again: the same
particles, colors and launch values. On an instance created with `fixedTimestep: true` the replay is exact,
motion included, on any display and at any frame rate:

```ts
const seed = Konfeti.fire({ particleCount: 80, spread: 90 }).getSeed();
setTimeout(() => Konfeti.fire({ particleCount: 80, spread: 90, seed }), 1200); // the same burst again
```

```ts
const stage = KonfetiFactory.create(canvas, { fixedTimestep: true }); // 1/60 s steps: exact replays
```

## The paper particle

The default confetti piece is fully configurable through `paper`:

```ts
Konfeti.fire({
  paper: {
    form: ["rect", "circle", { value: "strip", weight: 2 }], // weighted mix of silhouettes
    width: [6, 10],
    height: [12, 18],
    cornerRadius: 2, // or { tl: 6, br: 6 }
    skew: [-15, 15],
    colors: ["#ff0a54", "#ffd000", { color: "#00c2ff", weight: 3 }],
    backColor: "auto", // darkened front color while flipped
    stroke: { color: "white", width: 0.5 },
    gradient: { colors: ["gold", "orange"], angle: 45 },
    flip: { axis: "both", frequency: [0.5, 1.5] },
    wobble: { amplitude: [2, 8] },
    fadeOut: { start: 0.6, easing: "easeInQuad" },
    scaleOverLife: { to: 0.4 },
    shine: 0.5,
    trail: { length: 12 }, // a fading streak behind each piece
  },
});
```

Color themes: `KonfetiPalettes.PASTEL`, `GOLD`, `NEON`, `RAINBOW`, `WINTER`, `AUTUMN`, `OCEAN`, `CANDY`, `FOREST`,
`MONOCHROME` and `CLASSIC` are ready-made color lists — `paper: { colors: KonfetiPalettes.GOLD }`.

Forms: `rect`, `square`, `circle`, `strip`, `leaf`. Other style keys: `scale`, `colorMode`, `backShade`,
`colorOverLife`, `opacity`, `fadeIn`, `rotation`, `rotationSpeed`, `tilt`, `shadow`, `blendMode`, `trail` (it works on every
shape, e.g. `{ type: "star", trail: true }`).
Every option is documented in the type definitions — hover it in your editor.

## Shapes

Mix any shapes with weights. Style keys set in `paper` are the base for every shape; each entry can override
them.

```ts
Konfeti.fire({
  paper: { colors: ["#ff0a54", "#ffd000"] },
  shapes: [
    { type: "paper", weight: 4 },
    { type: "star", points: [5, 6], shine: 0.6 },
    { type: "heart", colors: "#ff4d6d" },
    { type: "emoji", emoji: ["🎉", "🥳", { value: "✨", weight: 3 }], size: [22, 32] },
    { type: "text", text: ["YAY", "WOW"], fontWeight: 900 },
    { type: "image", src: "/coin.png", size: [20, 30] },
    { type: "spritesheet", src: "/coin-spin.png", frames: { cols: 8, rows: 1 }, fps: 14 },
  ],
});
```

| Type          | Specific options                                                   |
| ------------- | ------------------------------------------------------------------ |
| `paper`       | paper geometry (see above)                                         |
| `star`        | `size`, `points`, `innerRatio`                                     |
| `triangle`    | `size`                                                             |
| `polygon`     | `size`, `sides`                                                    |
| `heart`       | `size`                                                             |
| `ribbon`      | `length`, `thickness`, `waves`                                     |
| `path`        | `path` (SVG `d` or `Path2D`), `viewBox`, `size`                    |
| `emoji`       | `emoji`, `size` (font size), `fontFamily`                          |
| `text`        | `text`, `size` (font size), `fontFamily`, `fontWeight`             |
| `image`       | `src` (URL or any canvas image source), `size` (width), `tint`     |
| `spritesheet` | `src`, `frames`, `fps`, `loop`, `randomStartFrame`, `size`, `tint` |

Emoji and text are rasterized once and cached. Preload URL images with `loadImage(url)`. An `image` or `spritesheet`
`src` that starts with `<svg` is used as inline SVG markup (give it a `width` and `height`; not supported in worker
mode).

`tint` paints images and spritesheets in the particle colors (`colors`, or the `paper` colors), so one white
artwork gives a whole palette. `true` multiplies the color in and keeps the shading; `"fill"` draws flat
silhouettes. Each color is painted once, so drawing costs the same as without a tint.

```ts
Konfeti.fire({
  shapes: [
    {
      type: "image",
      src: "/coin.png",
      size: [20, 30],
      tint: "fill",
      colors: ["#26ccff", "#ff5e7e"],
    },
  ],
});
```

A sheet packed by TexturePacker, Aseprite or Free Texture Packer comes with an atlas JSON: `framesFromAtlas`
turns it into `frames`, in atlas order, optionally only the frames whose name starts with a prefix.

```ts
import { Konfeti, framesFromAtlas } from "konfeti";
import atlas from "./coins.json";

Konfeti.fire({
  shapes: [{ type: "spritesheet", src: "/coins.png", frames: framesFromAtlas(atlas, "coin_spin") }],
});
```

## Physics

```ts
Konfeti.fire({
  physics: {
    gravity: 700, // px/s², negative floats upward
    drag: 3.5, // 1/s
    wind: [-40, 40], // px/s²
    terminalVelocity: 900, // px/s
    swirl: { strength: [80, 200], frequency: [0.3, 0.8] },
    floor: { y: 1, bounce: 0.35, friction: 0.4 }, // particles bounce and rest
    attract: { target: "pointer", strength: 900 }, // pulled toward the pointer; negative pushes away
  },
});
```

`attract` targets an element (measured every frame), `"pointer"` or a point like `{ x: 0.5, y: 0.2 }`; `radius`
limits its reach and `falloff: "linear"` fades it toward the edge.

## Emission

```ts
Konfeti.fire({ emission: { mode: "burst" } }); // default: everything at once
Konfeti.fire({ particleCount: 200, emission: { mode: "stream", duration: 3000 } }); // fountain
Konfeti.fire({
  particleCount: 50,
  emission: { mode: "interval", every: 350, times: 8 },
  origin: { x: [0.2, 0.8] },
});
```

Interval shots sample the origin once per shot — ranged origins produce fireworks at different spots.

`delay` starts a burst later (in milliseconds; paused time does not count). Give the entries of a list different
delays to choreograph them:

```ts
Konfeti.fire([
  { origin: { x: 0, y: 0.8 }, angle: 60 },
  { origin: { x: 1, y: 0.8 }, angle: 120, delay: 250 },
  { origin: { x: 0.5, y: 0.5 }, spread: 360, startVelocity: [500, 1000], delay: 700 },
]);
```

## Continuous emitter

`emit()` streams particles until you stop it — a fountain, a trail behind the pointer, sparks from an
element. It takes every `fire()` setting except `particleCount` / `origin` / `emission`, plus `rate`
(particles per second) and `follow`:

```ts
const trail = Konfeti.emit({
  rate: 60, // particles per second
  follow: "pointer", // or an element (measured every emission), or a point like { x: 0.5, y: 1 }
  spread: 360,
  startVelocity: [50, 150],
  lifetime: 800,
  shapes: [{ type: "star", size: [6, 10] }],
});

setTimeout(() => trail.stop(), 3000); // stop emitting; particles already out finish their lives
await trail; // resolves once the last one is gone
```

`trail.moveTo(target)` switches what it follows, `clear()` removes everything at once, and `pause()` /
`resume()` freeze it. Worker instances (`konfeti/worker`) emit too; the pointer or element is tracked on the
main thread.

## Formations

Particles first form a text or an image, hold it, then burst apart: a "You win!" end card, a launch
announcement, a logo reveal. Every shape can take part, and the rest of the burst options apply as usual once
the shape breaks up.

```ts
Konfeti.fire({
  origin: { x: 0.5, y: 0.45 }, // the center of the shape
  formation: {
    text: "TEBRİKLER",
    font: "900 110px sans-serif",
    mode: "assemble", // fly in from beyond the edges; "appear" shows the shape at once
    assemble: 900, // ms until the shape is complete
    hold: 1200, // ms before it bursts apart
    spacing: 8, // px between particles: smaller is denser and uses more particles
  },
  shapes: [{ type: "paper", weight: 3 }, { type: "star" }],
});
```

```ts
// an image: its opaque pixels become the shape, painted in the image's own colors
Konfeti.fire({
  formation: {
    image:
      '<svg width="220" height="200" viewBox="0 0 24 22"><path fill="#ff3d6e" d="M12 21s-9-6.1-9-12a5 5 0 0 1 9-3 5 5 0 0 1 9 3c0 5.9-9 12-9 12z"/></svg>',
    mode: "appear",
    hold: 1500,
  },
  startVelocity: [200, 500], // how fast the pieces fly outward when the shape breaks up
});
```

- The particle count follows from `spacing`; an explicit `particleCount` only caps it. When `maxParticles`
  caps it, the whole shape thins out evenly instead of losing a part.
- `fit` (default `0.9`) scales the whole formation (shape, spacing and particle size) down until it fits
  the canvas, so a phone shows a smaller copy of the same picture.
- `startVelocity` is the burst-apart speed, `[300, 700]` px/s unless you set it. The particles' `lifetime`
  starts when they are released, so the shape stays fully visible until then.
- An image can be a URL, inline SVG markup or any drawable image; the burst waits until it has loaded.
  `imageColors: false` keeps the shapes' own colors. A cross-origin image needs CORS headers.
- Worker instances form shapes too, with the fonts the worker can see; inline SVG is not supported there.
  Formations need a single burst (`emission: { mode: "burst" }`, the default) and are not available for
  `emit()`.

## Presets

```ts
import { Konfeti, KonfetiPresets, extendPreset } from "konfeti";

Konfeti.fire(KonfetiPresets.FIREWORKS);
Konfeti.fire(extendPreset(KonfetiPresets.SNOW, { emission: { mode: "stream", duration: 10000 } })); // your settings win
```

`BASIC`, `REALISTIC`, `CANNON`, `SIDE_SHOTS`, `SCHOOL_PRIDE`, `FIREWORKS`, `SNOW`, `STARS`, `EMOJI_RAIN`,
`HEART_BURST`, plus presets that show off newer options: `SHOOTING_STARS` (trails), `MAGNET` (attractor),
`FORCE_FIELD` (repulsor), `GOLDEN` (gold palette), `SPARKLER` and `FIREFLIES` (additive glow), `JACKPOT` (floor),
`CONGRATS`, `SUCCESS` and `LEVEL_UP` (text formations; `LEVEL_UP` is choreographed with `delay`) and `LOGO_REVEAL`
(image formation). Presets are plain, read-only options (`SIDE_SHOTS` and `SCHOOL_PRIDE` are two bursts). `extendPreset`
merges your settings into every burst without changing the preset; `paper` and `physics` merge key by key.

## Hooks

```ts
Konfeti.fire({
  onStart: () => {},
  onParticleSpawn: (p) => {},
  onParticleUpdate: (p, dt) => {}, // hot path, may mutate p.x / p.vx …
  onParticleDeath: (p) => {},
  onComplete: () => {},
});
```

## Instances & canvases

`Konfeti` is a shared fullscreen instance. Use `KonfetiFactory.create()` for your own canvas, separate defaults or a separate particle budget:

```ts
import { KonfetiFactory } from "konfeti";

const stage = KonfetiFactory.create(document.querySelector("canvas"), {
  maxParticles: 800,
  disableForReducedMotion: true,
  defaults: { paper: { colors: ["gold", "white"] } },
});

stage.fire({ particleCount: 80 });
const off = stage.onClick(document.querySelector("#like")!, { particleCount: 30 });
off(); // stop listening
stage.reset();
stage.destroy(); // also removes its click listeners
```

`onClick` takes a third argument: `trigger: "pointerdown"` fires as soon as a finger or button goes down (it
keeps working when the page cancels touch events), and `onFire` receives each click burst's handle:

```ts
Konfeti.onClick(
  button,
  { particleCount: 30 },
  {
    trigger: "pointerdown",
    onFire: (burst) => burst.then(() => console.log("done")),
  },
);
```

`pause()` freezes every burst on its current frame and `resume()` continues without counting the paused time
(hidden tabs pause on their own). Both exist on `Konfeti` and on every instance.

The first instance on a page logs a one-line banner with the version and renderer to the console. Call
`disableBanner()` before firing to keep the console silent (`konfeti/lite` never prints it).

## Worker rendering

`createWorker()` from `konfeti/worker` moves simulation and drawing into a Web Worker through an `OffscreenCanvas`, so
large bursts keep animating while the main thread is busy (heavy React renders, long tasks, scrolling):

```ts
import { createWorker } from "konfeti/worker"; // its own entry: other bundles carry no worker code

const stage = createWorker(document.querySelector("canvas"), { maxParticles: 3000 });

await stage.fire({
  particleCount: 1500,
  shapes: [{ type: "paper" }, { type: "emoji", emoji: "🎉" }],
});
stage.isWorker(); // false when the browser cannot render offscreen — it then runs on the main thread
stage.destroy(); // terminates the worker
```

Pass `null` (or nothing) for the canvas to get a fullscreen overlay, like `Konfeti`.

Options travel to the worker by `postMessage`, so they must be structured-cloneable. The types
(`WorkerFireOptions`) enforce this:

| Works in a worker                                      | Main thread only                                     |
| ------------------------------------------------------ | ---------------------------------------------------- |
| every paper, style, physics and emission option        | hooks (`onStart`, `onParticleSpawn`, `onComplete` …) |
| built-in shapes, emoji and text                        | custom `defineShape` / `definePhysics` modules       |
| `image` / `spritesheet` with a URL or an `ImageBitmap` | `HTMLImageElement`, `Path2D` and other DOM sources   |
| `origin` as a point, an element or a click event       | —                                                    |

Element and click origins are measured on the main thread before sending; the pointer or element that an
emitter follows or an attractor pulls toward is tracked there too and sent over while the burst runs. Use
`await` on the handle instead of `onComplete`.

The worker script itself (~19.1 kB brotli) is loaded only when the first worker instance is created. With a
bundler it is inlined as a `blob:` URL; the `<script>` build loads `konfeti.worker.js` from its own folder. For a
strict Content-Security-Policy without `worker-src blob:`, host `konfeti/konfeti.worker.js` yourself:

```ts
createWorker(canvas, { workerUrl: "/vendor/konfeti.worker.js" });
```

If the script cannot load, every burst rejects with a clear error instead of hanging.

Hooks cannot run inside a worker, so a worker instance counts for you: `stage.getStats()` returns
`{ live, spawned, died, completed }` (updated a few times per second).

## Playable ads & webviews

konfeti works in single-file playable ads: it has no dependencies, makes no network requests of its own, uses
no storage and no `eval`. `Konfeti.fire()` adds about 65 kB minified (20 kB brotli); ad networks usually count
uncompressed size. Keep these in mind:

- **Images:** pass a `data:` URI or an image / canvas your engine already loaded — a URL like `/coin.png` is a
  network request.
- **Web fonts:** text and emoji are drawn once and cached; a glyph drawn before its `@font-face` finished
  loading is redrawn automatically when the font arrives.
- **Emoji** look different on every platform (and old Android may lack new ones); use `image` shapes when the
  look must match.
- **Taps:** if your engine cancels touch events, `click` never fires on phones — use
  `onClick(target, options, { trigger: "pointerdown" })` or fire from your own input handler with
  `origin: { x, y }` (0–1) or the pointer event.
- **Visibility:** call `Konfeti.pause()` / `Konfeti.resume()` from MRAID `viewableChange`.
- **Low-end phones:** create the stage with `KonfetiFactory.create(null, { adaptiveQuality: true })`. On a slow
  device it renders at CSS resolution first, then drops shadows, shine and trails, then spawns fewer particles,
  and steps back up when frames are smooth again; `getQualityLevel()` tells the current level.
- **Worker rendering:** avoid it in ads — some webviews block `blob:` workers, and a single-file build that
  inlines dynamic imports carries the 62 kB worker script once you import `konfeti/worker`.
- **Console:** call `disableBanner()` in production builds.
- **Targets:** the build is ES2022 (Chrome 85+ / iOS 14.5+); let your bundler lower it for older webviews.

## Custom shapes & physics

Register your own shapes and physics modules — declare their options once and they are fully typed
everywhere.

```ts
import { Konfeti, defineShape, definePhysics } from "konfeti";

declare module "konfeti" {
  interface ShapeRegistry {
    diamond: { sharpness?: number };
  }
  interface PhysicsRegistry {
    magnet: { x: number; y: number; strength: number };
  }
}

// path-based: gradients, stroke, shine and flip work automatically
defineShape("diamond", {
  viewBox: [24, 24],
  path: ({ sharpness = 0.5 }) => `M12 0L${24 - sharpness * 12} 12L12 24L${sharpness * 12} 12Z`,
});

definePhysics("magnet", {
  defaults: { x: 0.5, y: 0.5, strength: 600 },
  apply: (p, dt, world, { x, y, strength }) => {
    p.vx += (x * world.width - p.x) * strength * dt * 0.001;
    p.vy += (y * world.height - p.y) * strength * dt * 0.001;
  },
});

Konfeti.fire({
  shapes: [{ type: "diamond", sharpness: 0.8 }],
  physics: { magnet: { strength: 900 } },
});
```

Draw-based shapes (`defineShape(name, { draw(ctx, particle, options) { … } })`) get full canvas control
with the transform already applied.

## Bundle size & `konfeti/lite`

| Usage                                                | Size (min + brotli) |
| ---------------------------------------------------- | ------------------- |
| `Konfeti` from `konfeti`                             | ~19.8 kB            |
| everything from `konfeti`                            | ~23.9 kB            |
| `Konfeti` from `konfeti/lite`                        | ~13.9 kB            |
| `createWorker` from `konfeti/worker`                 | ~21.9 kB            |
| worker script (loaded on the first `createWorker()`) | ~19.1 kB            |

`konfeti` registers every built-in shape for you. `konfeti/lite` starts with **paper only** — register just the
shapes you use and your bundler drops the rest:

```ts
import { Konfeti, registerShapes, starShape, emojiShape } from "konfeti/lite";

registerShapes(starShape, emojiShape);
Konfeti.fire({ shapes: [{ type: "star" }, { type: "emoji", emoji: "🎉" }] });
```

Presets live in the full entry only (they use several shapes). Formations are opt-in in lite too: call
`enableFormations()` once.

## Units & ranges

| Alias                      | Meaning                         |
| -------------------------- | ------------------------------- |
| `Pixels`                   | CSS pixels (before DPR scaling) |
| `Degrees`                  | 0 = right, 90 = up              |
| `Milliseconds`             | time                            |
| `Ratio`                    | 0–1 (clamped)                   |
| `Hertz`                    | cycles per second               |
| `PixelsPerSecond(Squared)` | speed / acceleration            |

Invalid options throw a `TypeError` that names the option (`"paper.width" must be a finite number`).

## AI assistants

konfeti ships an [Agent Skill](https://agentskills.io) in the package, `node_modules/konfeti/skills/konfeti`. It
teaches coding agents (Claude Code, Codex, Cursor, GitHub Copilot …) the entries, the core API, recipes, every
preset and shape, and the common pitfalls, and it always matches the installed version. Copy or link the folder
into your agent's skills folder, e.g. for Claude Code:

```sh
mkdir -p .claude/skills && cp -r node_modules/konfeti/skills/konfeti .claude/skills/
```

For chat assistants, the site serves the docs as Markdown:

- [`llms.txt`](https://konfeti.mbattaloglu.com/llms.txt): an index of the Markdown docs, for an assistant that
  can read links
- [`llms-full.txt`](https://konfeti.mbattaloglu.com/llms-full.txt): this guide and the whole API reference in one
  file, to paste or upload
- [`docs/index.md`](https://konfeti.mbattaloglu.com/docs/index.md): this guide alone

The guide's sidebar opens ChatGPT or Claude with a prompt that points at `llms.txt`, and the playground's Share &
Export tab copies a prompt with your current settings as JSON; paste the JSON an assistant returns into Options JSON
and load it into the controls.

## License

[MIT](https://github.com/mbattaloglu/konfeti/blob/main/LICENSE)

---

# API reference: konfeti

The full entry: `import { Konfeti } from "konfeti"`.
Every built-in shape is registered, presets are exported and new instances print the console banner
(`konfeti/lite` does none of these, so its bundles stay minimal).

## Classes

### KonfetiFactory

Konfeti Instance Factory.
Create dedicated instances for your own canvas, separate defaults or particle budgets. The everyday
fullscreen API is the shared `Konfeti` object; worker instances come from `createWorker` in `konfeti/worker`.

#### Constructors

##### Constructor

> **new KonfetiFactory**(): [`KonfetiFactory`](#konfetifactory)

###### Returns

[`KonfetiFactory`](#konfetifactory)

#### Methods

##### create()

> `static` **create**(`canvas?`, `options?`): [`KonfetiInstance`](#konfetiinstance)

Create Instance.

###### Parameters

###### canvas?

`HTMLCanvasElement` \| `null`

Target Canvas (`null` or omitted creates a fullscreen overlay on first `fire()`)

###### options?

[`CreateOptions`](#createoptions)

Instance Options

###### Returns

[`KonfetiInstance`](#konfetiinstance)

Konfeti Instance

###### Example

```ts
const stage = KonfetiFactory.create(document.querySelector("#stage"), {
  maxParticles: 800,
  defaults: { paper: { form: "circle" } },
});
stage.fire({ particleCount: 80 });
stage.destroy();
```

***

### KonfetiInstance

Konfeti Instance.
Binds a canvas (or a fullscreen overlay) to its own engine, pool and default options.

#### Example

```ts
const konfeti = new KonfetiInstance(document.querySelector("canvas"), { maxParticles: 500 });
await konfeti.fire({ particleCount: 100 });
konfeti.destroy();
```

#### Constructors

##### Constructor

> **new KonfetiInstance**(`canvas?`, `options?`): [`KonfetiInstance`](#konfetiinstance)

Create Instance.

###### Parameters

###### canvas?

`HTMLCanvasElement` \| `null`

Target Canvas (`null` or omitted creates a fullscreen overlay on first `fire()`)

###### options?

[`CreateOptions`](#createoptions) = `{}`

Instance Options

###### Returns

[`KonfetiInstance`](#konfetiinstance)

#### Methods

##### destroy()

> **destroy**(): `void`

Destroy Instance.
Stops everything, removes listeners and the overlay canvas. The instance cannot fire afterwards.

###### Returns

`void`

##### emit()

> **emit**(`options`): [`KonfetiEmitter`](#konfetiemitter)

Start a Continuous Emitter.
Streams particles at `rate` per second from what it follows (an element, the pointer or a point) until
you call `stop()`; the particles already out then finish their lives and the handle resolves.

###### Parameters

###### options

[`EmitOptions`](#emitoptions)

Emitter Options (every `fire()` setting except `particleCount`, `origin`, `emission`)

###### Returns

[`KonfetiEmitter`](#konfetiemitter)

Emitter Handle

###### Throws

TypeError for a missing, zero, negative or non-finite `rate` (and any invalid fire setting)

###### Example

```ts
const trail = Konfeti.emit({ rate: 40, follow: "pointer", spread: 360, startVelocity: [50, 150] });
setTimeout(() => trail.stop(), 3000);
await trail;
```

##### fire()

> **fire**(`input?`): [`KonfetiHandle`](#konfetihandle)

Fire Burst (or Several Bursts at Once).

###### Parameters

###### input?

[`FireInput`](#fireinput) = `{}`

Burst Options (merged over the instance `defaults`), or an array of them

###### Returns

[`KonfetiHandle`](#konfetihandle)

Awaitable Burst Handle (a combined handle for arrays)

###### Throws

Error when the instance was destroyed, TypeError on invalid options

##### getCanvas()

> **getCanvas**(): `HTMLCanvasElement`

Return Canvas Element.

###### Returns

`HTMLCanvasElement`

Canvas Element

##### getParticleCount()

> **getParticleCount**(): `number`

Return Live Particle Count.

###### Returns

`number`

Live Particle Count

##### getQualityLevel()

> **getQualityLevel**(): `number`

Return the Adaptive Quality Level.
Always `0` without the `adaptiveQuality` option.

###### Returns

`number`

Level: `0` full quality, `1` CSS resolution, `2` no shadows / shine / trails, `3` fewer particles

##### isDestroyed()

> **isDestroyed**(): `boolean`

Return Destroyed State.

###### Returns

`boolean`

Destroyed State

##### isPaused()

> **isPaused**(): `boolean`

Check Whether pause() Is in Effect.

###### Returns

`boolean`

Paused Flag

##### onClick()

> **onClick**(`target`, `options?`, `settings?`): () => `void`

Fire on Every Click.
Bursts start at the click position unless the options set their own `origin`.

###### Parameters

###### target

`Element` \| `Window`

Element (or `window`) to Listen On

###### options?

[`FireInput`](#fireinput) \| ((`event`) => [`FireInput`](#fireinput))

Burst Options, or a Function Building Them from the Click Event

###### settings?

[`ClickOptions`](#clickoptions) = `{}`

Trigger Event and Burst Callback

###### Returns

Unsubscribe Function

() => `void`

###### Example

```ts
const off = Konfeti.onClick(document.querySelector("#like")!, { particleCount: 30, spread: 70 });
off(); // stop listening
```

##### pause()

> **pause**(): `void`

Pause Everything.
Freezes every running burst on its current frame; bursts fired while paused wait as well. Use it when
the confetti is not visible, e.g. on an MRAID `viewableChange` in a playable ad. Hidden tabs already
pause automatically.

###### Returns

`void`

###### Example

```ts
mraid.addEventListener("viewableChange", (viewable) => {
  if (viewable) Konfeti.resume();
  else Konfeti.pause();
});
```

##### reset()

> **reset**(): `void`

Stop All Bursts and Clear Canvas.

###### Returns

`void`

##### resume()

> **resume**(): `void`

Resume After pause().
Continues exactly where the bursts stopped; the paused time does not count as elapsed.

###### Returns

`void`

## Interfaces

### PhysicsRegistry

Custom Physics Registry.
Empty by default. Augment it to declare options of modules added with `definePhysics()`; they then
appear as typed keys of `physics`.

#### Example

```ts
declare module "konfeti" {
  interface PhysicsRegistry {
    magnet: { x?: number; y?: number; strength?: number };
  }
}
Konfeti.fire({ physics: { magnet: { strength: 900 } } });
```

***

### ShapeRegistry

Custom Shape Registry.
Empty by default. Augment it to declare the options of shapes you add with `defineShape()`, so
`Konfeti.fire({ shapes: [{ type: "yourShape", ... }] })` is fully typed.

#### Example

```ts
declare module "konfeti" {
  interface ShapeRegistry {
    diamond: { sharpness?: number };
  }
}
```

## Type Aliases

### AnyShapeHandler

> **AnyShapeHandler** = `object`

Shape Handler of Any Entry Type.
What registries store: `resolve` accepts `never` so every concrete handler is assignable.

#### Properties

##### resolve

> `readonly` **resolve**: (`entry`, `context`) => `ResolvedShape`

Resolve Entry.

###### Parameters

###### entry

`never`

###### context

[`ShapeHandlerContext`](#shapehandlercontext)

###### Returns

`ResolvedShape`

##### styleDefaults?

> `readonly` `optional` **styleDefaults?**: [`ShapeStyle`](#shapestyle)

Style Defaults for This Type.

##### type

> `readonly` **type**: `string`

Handled Shape Type.

***

### AttractFalloff

> **AttractFalloff** = `"constant"` \| `"linear"`

How the Pull of an Attractor Changes with Distance.
- `"constant"`: the same pull everywhere inside the radius;
- `"linear"`: full pull at the target, fading to nothing at the radius (needs a finite `radius`).

***

### AttractOptions

> **AttractOptions** = `object`

Attractor / Repulsor Settings.
Pulls every particle toward a target — the pointer, an element or a point — or pushes it away with a negative
`strength`. The target is looked up once per frame, so it can move.

#### Example

```ts
Konfeti.fire({ physics: { attract: true } }); // pulled toward the pointer
Konfeti.fire({ physics: { attract: { target: basket, strength: 1500 } } }); // into an element
Konfeti.fire({ physics: { attract: { target: "pointer", strength: -2000, radius: 150 } } }); // pushed away
```

#### Properties

##### falloff?

> `readonly` `optional` **falloff?**: [`AttractFalloff`](#attractfalloff)

Distance Falloff.

###### Default Value

`"constant"`

###### See

[AttractFalloff](#attractfalloff)

##### radius?

> `readonly` `optional` **radius?**: [`Pixels`](#pixels)

Reach.
Particles farther than this from the target are not affected. `Infinity` reaches the whole canvas.

###### Default Value

`Infinity`

###### Remarks

Unit: pixels (CSS px).

##### strength?

> `readonly` `optional` **strength?**: [`Range`](#range)\<[`PixelsPerSecondSquared`](#pixelspersecondsquared)\>

Pull Strength.
Acceleration toward the target; a negative value pushes particles away (a repulsor). Sampled per particle,
so a range makes some pieces react more than others.

###### Default Value

`900`

###### Remarks

Unit: pixels per second squared. Gravity and drag still apply, so a pull weaker than `gravity`
slows the fall rather than lifting particles.

##### target?

> `readonly` `optional` **target?**: [`EmitterTarget`](#emittertarget)

Target.
An element (its center, measured every frame), `"pointer"` (no pull until the pointer moves over the page)
or a normalized point `{ x, y }` (0–1 of the canvas).

###### Default Value

`"pointer"`

###### Remarks

Worker instances follow the pointer or element on the main thread and send every new place to the
worker.

***

### BuiltinPhysicsOptions

> **BuiltinPhysicsOptions** = `object`

Built-in Motion Physics Settings.
Range values are sampled per particle, so pieces fall at slightly different rates.
Horizontal terminal speed is `wind / drag`, vertical terminal speed is `gravity / drag`.

#### Properties

##### attract?

> `readonly` `optional` **attract?**: `boolean` \| [`AttractOptions`](#attractoptions)

Attractor / Repulsor.
`true` pulls particles toward the pointer with the default strength, `false` disables it, an object sets the
target (pointer, element or point), strength (negative pushes away), reach and falloff.

###### Default Value

`false`

###### Example

```ts
Konfeti.fire({ physics: { attract: true } });
Konfeti.fire({ physics: { attract: { target: { x: 0.5, y: 0.2 }, strength: 1200 } } });
```

###### See

[AttractOptions](#attractoptions)

##### drag?

> `readonly` `optional` **drag?**: [`Range`](#range)\<[`PerSecond`](#persecond)\>

Air Resistance.
How quickly particles lose speed. `0` = no resistance, higher = shorter bursts and slower falling.

###### Default Value

`3.5`

##### floor?

> `readonly` `optional` **floor?**: `boolean` \| [`FloorOptions`](#flooroptions)

Floor Collision.
`true` uses the canvas bottom with default bounce, `false` lets particles fall off-screen.

###### Default Value

`false`

###### See

[FloorOptions](#flooroptions)

##### gravity?

> `readonly` `optional` **gravity?**: [`Range`](#range)\<[`PixelsPerSecondSquared`](#pixelspersecondsquared)\>

Downward Acceleration.
Negative values make particles float upward.

###### Default Value

`700`

##### swirl?

> `readonly` `optional` **swirl?**: `boolean` \| [`SwirlOptions`](#swirloptions)

Looping Drift.
`true` uses the default swirl, `false` disables it, an object customizes it.

###### Default Value

`false`

###### See

[SwirlOptions](#swirloptions)

##### terminalVelocity?

> `readonly` `optional` **terminalVelocity?**: [`PixelsPerSecond`](#pixelspersecond)

Speed Limit.
Caps the total speed of every particle. `Infinity` disables the cap.

###### Default Value

`Infinity`

##### wind?

> `readonly` `optional` **wind?**: [`Range`](#range)\<[`PixelsPerSecondSquared`](#pixelspersecondsquared)\>

Horizontal Acceleration.
Positive pushes right, negative pushes left.

###### Default Value

`0`

***

### BuiltinShapeOptions

> **BuiltinShapeOptions** = [`PaperShapeOptions`](#papershapeoptions) \| [`StarShapeOptions`](#starshapeoptions) \| [`TriangleShapeOptions`](#triangleshapeoptions) \| [`PolygonShapeOptions`](#polygonshapeoptions) \| [`HeartShapeOptions`](#heartshapeoptions) \| [`RibbonShapeOptions`](#ribbonshapeoptions) \| [`PathShapeOptions`](#pathshapeoptions) \| [`EmojiShapeOptions`](#emojishapeoptions) \| [`TextShapeOptions`](#textshapeoptions) \| [`ImageShapeOptions`](#imageshapeoptions) \| [`SpriteSheetShapeOptions`](#spritesheetshapeoptions)

Built-in `shapes` Entry.

***

### BuiltinShapeType

> **BuiltinShapeType** = [`BuiltinShapeOptions`](#builtinshapeoptions)\[`"type"`\]

Built-in Shape Type Name.

***

### BurstHooks

> **BurstHooks** = `object`

Burst Lifecycle Hooks.

#### Example

```ts
Konfeti.fire({
  onParticleDeath: (p) => sparkAt(p.x, p.y),
  onComplete: () => console.log("done"),
});
```

#### Properties

##### onComplete?

> `readonly` `optional` **onComplete?**: () => `void`

Complete Callback.
Called when emission has ended and every particle is gone (also after `stop()`).

###### Returns

`void`

##### onParticleDeath?

> `readonly` `optional` **onParticleDeath?**: (`particle`) => `void`

Particle Death Callback.
Called before the particle returns to the pool; do not keep the reference.

###### Parameters

###### particle

[`ParticleState`](#particlestate)

###### Returns

`void`

##### onParticleSpawn?

> `readonly` `optional` **onParticleSpawn?**: (`particle`) => `void`

Particle Spawn Callback.

###### Parameters

###### particle

[`ParticleState`](#particlestate)

###### Returns

`void`

##### onParticleUpdate?

> `readonly` `optional` **onParticleUpdate?**: (`particle`, `dt`) => `void`

Particle Update Callback.
Called for every live particle every frame, after physics.

###### Parameters

###### particle

[`MutableParticle`](#mutableparticle)

###### dt

`number`

###### Returns

`void`

###### Remarks

Runs in the hot path — keep it allocation-free.

##### onStart?

> `readonly` `optional` **onStart?**: () => `void`

Start Callback.
Called once, right after the first particles spawn.

###### Returns

`void`

***

### ClickOptions

> **ClickOptions** = `object`

Click Listener Settings (third argument of `onClick`).

#### Example

```ts
// fire on press, and keep each burst's handle
Konfeti.onClick(button, { particleCount: 30 }, {
  trigger: "pointerdown",
  onFire: (burst) => burst.then(() => console.log("done")),
});
```

#### Properties

##### onFire?

> `readonly` `optional` **onFire?**: (`handle`, `event`) => `void`

Burst Callback.
Called with the handle of every burst the listener fires, and the event that fired it. Use it to pause,
stop or `await` click bursts, which `onClick` itself cannot return.

###### Parameters

###### handle

[`KonfetiHandle`](#konfetihandle)

###### event

`MouseEvent`

###### Returns

`void`

###### Default Value

```ts
none
```

##### trigger?

> `readonly` `optional` **trigger?**: `"click"` \| `"pointerdown"`

Trigger Event.
`"click"` fires when a click completes. `"pointerdown"` fires as soon as the mouse button, finger or pen
goes down: it feels snappier and keeps working when the page cancels touch events (common in games and
playable ads, where `preventDefault()` on touch suppresses `click`).

###### Default Value

`"click"`

***

### ClientPoint

> **ClientPoint** = `object`

Viewport Point.
Any object with `clientX` / `clientY` — a `MouseEvent`, `PointerEvent` or `Touch` works directly.

#### Example

```ts
button.addEventListener("click", (event) => Konfeti.fire({ origin: event }));
```

#### Properties

##### clientX

> `readonly` **clientX**: `number`

Horizontal Viewport Coordinate.

##### clientY

> `readonly` **clientY**: `number`

Vertical Viewport Coordinate.

***

### ColorInput

> **ColorInput** = [`HexColor`](#hexcolor) \| [`RgbColor`](#rgbcolor) \| [`HslColor`](#hslcolor) \| [`ModernCssColor`](#moderncsscolor) \| [`CssColorName`](#csscolorname)

Any Supported CSS Color.
Invalid colors throw a `TypeError` when `Konfeti.fire()` is called, so typos surface immediately.

#### Example

```ts
"#ff0a54" | "rgb(255 208 0)" | "hsl(200 100% 50%)" | "oklch(70% 0.2 30)" | "hotpink"
```

***

### ColorMode

> **ColorMode** = `"random"` \| `"sequence"`

Color Pick Strategy.
- `"random"` — each particle picks a random color; `weight` values are respected.
- `"sequence"` — colors are used in list order, looping (particle 1 → color 1, particle 2 → color 2 …).
  Weights are ignored.

***

### ColorOverLifeOptions

> **ColorOverLifeOptions** = `object`

Color Transition over Lifetime.
Each particle blends from its picked front color to `to` as it ages.

#### Example

```ts
paper: { colors: ["#fff6a0"], colorOverLife: { to: "#ff3300", easing: "easeInQuad" } } // embers
```

#### Remarks

Colors are precomputed into a small lookup table per palette color; no per-frame string building.

#### Properties

##### easing?

> `readonly` `optional` **easing?**: [`Easing`](#easing-1)

Transition Curve.

###### Default Value

`"linear"`

##### to

> `readonly` **to**: [`ColorInput`](#colorinput)

End Color.

***

### ColorSource

> **ColorSource** = [`ColorInput`](#colorinput) \| readonly ([`ColorInput`](#colorinput) \| [`WeightedColor`](#weightedcolor))[]

Single Color or Color List.
With a list, each particle picks one entry (see `colorMode`). Lists may mix plain and weighted colors.

#### Example

```ts
colors: "gold"
colors: ["#ff0a54", "#ffd000", "#00c2ff"]
colors: [{ color: "gold", weight: 4 }, "silver"]
```

***

### CornerRadii

> **CornerRadii** = `object`

Per-Corner Radius Map.
Omitted corners stay sharp (`0`).

#### Properties

##### bl?

> `readonly` `optional` **bl?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Bottom-Left Corner Radius.

##### br?

> `readonly` `optional` **br?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Bottom-Right Corner Radius.

##### tl?

> `readonly` `optional` **tl?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Top-Left Corner Radius.

##### tr?

> `readonly` `optional` **tr?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Top-Right Corner Radius.

***

### CornerRadius

> **CornerRadius** = [`Range`](#range)\<[`Pixels`](#pixels)\> \| [`CornerRadii`](#cornerradii)

Corner Radius for All Corners or per Corner.
A number (or range) rounds every corner equally; a [CornerRadii](#cornerradii) object sets each corner separately.
Radii are clamped to half of the particle's shorter side.

***

### CreateOptions

> **CreateOptions** = `object`

Options for a Konfeti Instance.

#### Example

```ts
const konfeti = KonfetiFactory.create(myCanvas, {
  maxParticles: 800,
  defaults: { paper: { colors: ["gold", "white"] } },
});
```

#### Properties

##### adaptiveQuality?

> `readonly` `optional` **adaptiveQuality?**: `boolean`

Adaptive Quality.
Watches the frame rate while particles animate. When frames stay slow (below about 50 fps) and konfeti's
own drawing is a real part of the cost, the quality steps down one level at a time: `1` renders at CSS
resolution, `2` also drops shadows, shine and trails, `3` also spawns 60% of the requested particles.
After a few seconds of smooth frames it steps back up.

###### Default Value

`false` (always full quality)

###### Example

```ts
const stage = KonfetiFactory.create(null, { adaptiveQuality: true }); // fullscreen, like Konfeti
stage.fire(KonfetiPresets.FIREWORKS);
stage.getQualityLevel(); // 0 on a fast device
```

###### Remarks

A busy page or a screen locked at 30 Hz (e.g. a phone's low-power mode) does not lower the
quality, since drawing less would not help there. With `fixedTimestep`, level `3` is skipped so replays
spawn the same particles.

##### defaults?

> `readonly` `optional` **defaults?**: [`FireOptions`](#fireoptions)

Instance Default Burst Options.
Merged under every `fire()` call on this instance (fire options win). Nested groups such as `paper` and
`physics` are merged key by key.

###### Default Value

`{}`

##### disableForReducedMotion?

> `readonly` `optional` **disableForReducedMotion?**: `boolean`

Respect Reduced Motion.
When `true` and the user has `prefers-reduced-motion: reduce`, `fire()` draws nothing and its handle
resolves immediately.

###### Default Value

`false`

##### fixedTimestep?

> `readonly` `optional` **fixedTimestep?**: `boolean`

Fixed Time Step.
Simulate in fixed 1/60 s steps instead of the real frame time. A burst fired again with the same `seed`
(and the same options and canvas size) then replays exactly, particle for particle, on any display and at
any frame rate. Motion updates 60 times per second, also on faster screens.

###### Default Value

`false` (each frame simulates the real time since the last one)

###### Example

```ts
const stage = KonfetiFactory.create(canvas, { fixedTimestep: true });
const seed = stage.fire().getSeed();
stage.fire({ seed }); // exactly the same burst again
```

###### Remarks

Useful for replays, demos and visual tests. Without it, the same seed still gives the same
particles, but their paths can differ slightly with the frame timing.

##### frameScheduler?

> `readonly` `optional` **frameScheduler?**: [`FrameScheduler`](#framescheduler-1)

Custom Frame Scheduler.
Replaces `requestAnimationFrame`. Intended for tests and custom render loops.

###### Default Value

`window.requestAnimationFrame`

##### maxDevicePixelRatio?

> `readonly` `optional` **maxDevicePixelRatio?**: `number`

Device Pixel Ratio Cap.
Limits canvas resolution on very dense screens to save GPU time. `1` renders at CSS resolution.

###### Default Value

`2`

##### maxParticles?

> `readonly` `optional` **maxParticles?**: `number`

Maximum Live Particles.
When a new burst would exceed it, the oldest particles are removed first.

###### Default Value

`1500`

##### resize?

> `readonly` `optional` **resize?**: `boolean`

Automatic Canvas Resize.
Keeps the canvas' pixel size in sync with its CSS size (and the window, for the built-in overlay canvas).
Disable if you manage the canvas size yourself.

###### Default Value

`true`

##### zIndex?

> `readonly` `optional` **zIndex?**: `number`

Overlay Canvas z-index.
Only used by the built-in fullscreen canvas (when no canvas is passed to `KonfetiFactory.create()`).

###### Default Value

`100`

***

### CssColorName

> **CssColorName** = `"transparent"` \| `"aliceblue"` \| `"antiquewhite"` \| `"aqua"` \| `"aquamarine"` \| `"azure"` \| `"beige"` \| `"bisque"` \| `"black"` \| `"blanchedalmond"` \| `"blue"` \| `"blueviolet"` \| `"brown"` \| `"burlywood"` \| `"cadetblue"` \| `"chartreuse"` \| `"chocolate"` \| `"coral"` \| `"cornflowerblue"` \| `"cornsilk"` \| `"crimson"` \| `"cyan"` \| `"darkblue"` \| `"darkcyan"` \| `"darkgoldenrod"` \| `"darkgray"` \| `"darkgreen"` \| `"darkgrey"` \| `"darkkhaki"` \| `"darkmagenta"` \| `"darkolivegreen"` \| `"darkorange"` \| `"darkorchid"` \| `"darkred"` \| `"darksalmon"` \| `"darkseagreen"` \| `"darkslateblue"` \| `"darkslategray"` \| `"darkslategrey"` \| `"darkturquoise"` \| `"darkviolet"` \| `"deeppink"` \| `"deepskyblue"` \| `"dimgray"` \| `"dimgrey"` \| `"dodgerblue"` \| `"firebrick"` \| `"floralwhite"` \| `"forestgreen"` \| `"fuchsia"` \| `"gainsboro"` \| `"ghostwhite"` \| `"gold"` \| `"goldenrod"` \| `"gray"` \| `"green"` \| `"greenyellow"` \| `"grey"` \| `"honeydew"` \| `"hotpink"` \| `"indianred"` \| `"indigo"` \| `"ivory"` \| `"khaki"` \| `"lavender"` \| `"lavenderblush"` \| `"lawngreen"` \| `"lemonchiffon"` \| `"lightblue"` \| `"lightcoral"` \| `"lightcyan"` \| `"lightgoldenrodyellow"` \| `"lightgray"` \| `"lightgreen"` \| `"lightgrey"` \| `"lightpink"` \| `"lightsalmon"` \| `"lightseagreen"` \| `"lightskyblue"` \| `"lightslategray"` \| `"lightslategrey"` \| `"lightsteelblue"` \| `"lightyellow"` \| `"lime"` \| `"limegreen"` \| `"linen"` \| `"magenta"` \| `"maroon"` \| `"mediumaquamarine"` \| `"mediumblue"` \| `"mediumorchid"` \| `"mediumpurple"` \| `"mediumseagreen"` \| `"mediumslateblue"` \| `"mediumspringgreen"` \| `"mediumturquoise"` \| `"mediumvioletred"` \| `"midnightblue"` \| `"mintcream"` \| `"mistyrose"` \| `"moccasin"` \| `"navajowhite"` \| `"navy"` \| `"oldlace"` \| `"olive"` \| `"olivedrab"` \| `"orange"` \| `"orangered"` \| `"orchid"` \| `"palegoldenrod"` \| `"palegreen"` \| `"paleturquoise"` \| `"palevioletred"` \| `"papayawhip"` \| `"peachpuff"` \| `"peru"` \| `"pink"` \| `"plum"` \| `"powderblue"` \| `"purple"` \| `"rebeccapurple"` \| `"red"` \| `"rosybrown"` \| `"royalblue"` \| `"saddlebrown"` \| `"salmon"` \| `"sandybrown"` \| `"seagreen"` \| `"seashell"` \| `"sienna"` \| `"silver"` \| `"skyblue"` \| `"slateblue"` \| `"slategray"` \| `"slategrey"` \| `"snow"` \| `"springgreen"` \| `"steelblue"` \| `"tan"` \| `"teal"` \| `"thistle"` \| `"tomato"` \| `"turquoise"` \| `"violet"` \| `"wheat"` \| `"white"` \| `"whitesmoke"` \| `"yellow"` \| `"yellowgreen"`

CSS Named Color.

***

### CustomPhysicsOptions

> **CustomPhysicsOptions** = \{ readonly \[K in keyof PhysicsRegistry\]?: boolean \| Partial\<PhysicsRegistry\[K\]\> \}

Custom Physics Module Keys (from `definePhysics()` via [PhysicsRegistry](#physicsregistry)).
`true` enables a module with its defaults, an object customizes it, `false` disables it.

***

### CustomShapeOptions

> **CustomShapeOptions** = `{ [K in keyof ShapeRegistry]: ShapeEntryBase & ShapeRegistry[K] & { size?: Range<Pixels>; type: K } }`\[keyof [`ShapeRegistry`](#shaperegistry)\]

Entry for a Shape Registered with `defineShape()`.
One union member per [ShapeRegistry](#shaperegistry) key; `never` while the registry is empty.

***

### CustomShapeParticle

> **CustomShapeParticle** = `object`

Particle View Passed to a Custom `draw()` Function.
The context is already translated, rotated, flipped, skewed, scaled and faded; draw centered at `0, 0`
inside a `width × height` box. The object is reused between calls — read it, don't keep it.

#### Properties

##### facing

> `readonly` **facing**: `number`

Facing (`> 0` front side, `< 0` back side while flipping).

##### fill

> `readonly` **fill**: `string` \| `CanvasGradient`

Fill Style for the Current Side and Age (color, gradient or back color).

##### height

> `readonly` **height**: `number`

Box Height in Local Pixels.

##### progress

> `readonly` **progress**: `number`

Life Progress (`0` = just spawned, `1` = about to die).

##### stroke

> `readonly` **stroke**: `string` \| `null`

Stroke Color (`null` when stroke is off).

##### strokeWidth

> `readonly` **strokeWidth**: `number`

Stroke Width in Local Pixels.

##### width

> `readonly` **width**: `number`

Box Width in Local Pixels.

***

### Degrees

> **Degrees** = `number`

Angle in Degrees.
`0` points right, `90` points up, `180` points left, `270` points down.

***

### DegreesPerSecond

> **DegreesPerSecond** = `number`

Angular Speed in Degrees per Second.

***

### DrawShapeDefinition

> **DrawShapeDefinition**\<`TOptions`\> = `object`

Draw-Based Custom Shape.
Full control: draw anything with the 2D context. The library has already applied position, rotation,
flip, skew, scale and opacity — draw centered at `0, 0`.

#### Example

```ts
defineShape("ring", {
  draw: (ctx, p, { thickness = 3 }) => {
    ctx.lineWidth = thickness;
    ctx.strokeStyle = p.fill;
    ctx.beginPath();
    ctx.arc(0, 0, p.width / 2, 0, Math.PI * 2);
    ctx.stroke();
  },
});
```

#### Remarks

Runs for every particle every frame — avoid allocations inside `draw`.

#### Type Parameters

##### TOptions

`TOptions` *extends* `object`

#### Properties

##### aspectRatio?

> `readonly` `optional` **aspectRatio?**: `number`

Height-to-Width Ratio of the Box.

###### Default Value

`1`

##### defaultSize?

> `readonly` `optional` **defaultSize?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Size When the Entry Sets None.

###### Default Value

`[12, 18]`

##### draw

> `readonly` **draw**: (`context`, `particle`, `options`) => `void`

Draw One Particle.

###### Parameters

###### context

`CanvasRenderingContext2D`

###### particle

[`CustomShapeParticle`](#customshapeparticle)

###### options

`Readonly`\<`TOptions`\>

###### Returns

`void`

***

### Easing

> **Easing** = [`EasingName`](#easingname) \| [`EasingFunction`](#easingfunction)

Easing Name or Custom Easing Function.

#### Example

```ts
easing: "easeOutCubic"
easing: (t) => t * t * t
```

***

### EasingFunction

> **EasingFunction** = (`t`) => `number`

Custom Easing Function.
Receives progress `t` in `0–1` and returns the eased progress (usually `0–1`).

#### Parameters

##### t

`number`

#### Returns

`number`

***

### EasingName

> **EasingName** = `"linear"` \| `"easeInQuad"` \| `"easeOutQuad"` \| `"easeInOutQuad"` \| `"easeInCubic"` \| `"easeOutCubic"` \| `"easeInOutCubic"`

Built-in Easing Name.

***

### EmissionOptions

> **EmissionOptions** = \{ `mode`: `"burst"`; \} \| \{ `duration`: [`Milliseconds`](#milliseconds); `mode`: `"stream"`; \} \| \{ `every`: [`Milliseconds`](#milliseconds); `mode`: `"interval"`; `times`: `number`; \}

Emission Timing.
- `"burst"` — all `particleCount` particles at once (default).
- `"stream"` — `particleCount` particles spread evenly over `duration` (a continuous fountain).
- `"interval"` — `particleCount` particles every `every` ms, `times` times. The origin is re-sampled for
  each shot, so ranged origins produce fireworks at different spots.

#### Union Members

##### Type Literal

\{ `mode`: `"burst"`; \}

###### mode

> `readonly` **mode**: `"burst"`

Emission Mode.

***

##### Type Literal

\{ `duration`: [`Milliseconds`](#milliseconds); `mode`: `"stream"`; \}

###### duration

> `readonly` **duration**: [`Milliseconds`](#milliseconds)

Stream Duration.

###### mode

> `readonly` **mode**: `"stream"`

Emission Mode.

***

##### Type Literal

\{ `every`: [`Milliseconds`](#milliseconds); `mode`: `"interval"`; `times`: `number`; \}

###### every

> `readonly` **every**: [`Milliseconds`](#milliseconds)

Time between Shots.

###### mode

> `readonly` **mode**: `"interval"`

Emission Mode.

###### times

> `readonly` **times**: `number`

Number of Shots.

#### Example

```ts
emission: { mode: "stream", duration: 3000 }
emission: { mode: "interval", every: 400, times: 6 }
```

***

### EmitOptions

> **EmitOptions** = `Omit`\<[`FireOptions`](#fireoptions), `"particleCount"` \| `"origin"` \| `"emission"` \| `"formation"`\> & `object`

Continuous Emitter Options.
Everything `fire()` accepts (shapes, paper, physics, hooks …) except the settings a stream replaces:
`particleCount` becomes `rate`, `origin` becomes `follow`, and `emission` is always continuous. A stream
cannot form a shape, so `formation` is not available either.

#### Type Declaration

##### follow?

> `readonly` `optional` **follow?**: [`EmitterTarget`](#emittertarget)

Emission Point.
An element, `"pointer"` or a normalized point; change it later with `emitter.moveTo()`.

###### Default Value

`{ x: 0.5, y: 0.6 }` (the same point `fire()` uses)

###### See

[EmitterTarget](#emittertarget)

##### rate

> `readonly` **rate**: `number`

Emission Rate.
How many particles leave the emitter per second, spread evenly over time. Must be a positive, finite
number; the instance's `maxParticles` still caps the total on screen.

###### Remarks

Unit: particles per second.

###### Example

```ts
Konfeti.emit({ rate: 25 }); // a gentle fountain
```

#### Example

```ts
const trail = Konfeti.emit({
  rate: 40,
  follow: "pointer",
  spread: 360,
  startVelocity: [50, 150],
  shapes: [{ type: "star", size: [8, 12] }],
});
trail.stop(); // stop emitting; the particles already out finish their lives
```

***

### EmitterTarget

> **EmitterTarget** = `Element` \| `"pointer"` \| [`OriginPoint`](#originpoint)

What a Continuous Emitter Follows.
- an **element**: particles start from its center, measured at every emission (so it can move or animate);
- `"pointer"`: the mouse / finger position — nothing is emitted until the pointer first moves over the page;
- a **normalized point** `{ x, y }` (0–1 of the canvas, ranges allowed), like `fire({ origin })`.

#### Example

```ts
Konfeti.emit({ rate: 30, follow: document.querySelector("#rocket")! });
Konfeti.emit({ rate: 60, follow: "pointer" });
Konfeti.emit({ rate: 20, follow: { x: [0, 1], y: 0 } }); // along the top edge
```

***

### EmojiShapeOptions

> **EmojiShapeOptions** = [`ShapeEntryBase`](#shapeentrybase) & `object`

Emoji Shape Entry.
Each emoji is rendered once into a cached bitmap and then drawn like a sprite. Color and stroke keys are
ignored.

#### Type Declaration

##### emoji

> `readonly` **emoji**: [`OneOrMany`](#oneormany)\<`string`\>

Emoji Character(s).
Any grapheme works, including ZWJ sequences and flags.

##### fontFamily?

> `readonly` `optional` **fontFamily?**: `string`

Font Family Stack.

###### Default Value

`'"Apple Color Emoji", "Segoe UI Emoji", "Noto Color Emoji", sans-serif'`

##### size?

> `readonly` `optional` **size?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Emoji Size (font size).

###### Default Value

`[18, 28]`

##### type

> `readonly` **type**: `"emoji"`

Shape Type.

#### Example

```ts
shapes: [{ type: "emoji", emoji: ["🎉", "🥳", { value: "✨", weight: 3 }], size: [20, 32] }]
```

***

### FadeOutOptions

> **FadeOutOptions** = `object`

Fade-Out Settings.

#### Properties

##### easing?

> `readonly` `optional` **easing?**: [`Easing`](#easing-1)

Fade Curve.
Applied to the fade progress. `"easeInQuad"` keeps particles visible longer and drops off at the end.

###### Default Value

`"linear"`

##### start?

> `readonly` `optional` **start?**: [`Ratio`](#ratio)

Fade Start Point.
Fraction of the particle's lifetime after which it starts fading. `0.7` means it is fully visible for the
first 70% of its life and fades to transparent during the last 30%.

###### Default Value

`0.7`

***

### FireInput

> **FireInput** = [`FireOptions`](#fireoptions) \| readonly [`FireOptions`](#fireoptions)[]

One Burst or Several Bursts Fired Together.
An array fires every entry at once and returns one combined handle (presets use this).

***

### FireOptions

> **FireOptions** = [`BurstHooks`](#bursthooks) & `object`

Options for a Single Burst.
Everything is optional — `Konfeti.fire()` with no arguments produces a classic confetti pop.

#### Type Declaration

##### angle?

> `readonly` `optional` **angle?**: [`Range`](#range)\<[`Degrees`](#degrees)\>

Launch Direction.
`90` shoots straight up, `0` right, `180` left, `270` down.

###### Default Value

`90`

##### delay?

> `readonly` `optional` **delay?**: [`Milliseconds`](#milliseconds)

Start Delay.
Waits this long after `fire()` before the burst starts. Give the entries of a list different delays to
choreograph them: a cannon shot, then a message, then a finale.

###### Default Value

`0`

###### Example

```ts
Konfeti.fire([
  { origin: { x: 0, y: 0.8 }, angle: 60 },
  { origin: { x: 1, y: 0.8 }, angle: 120, delay: 250 },
  { formation: { text: "HOORAY" }, delay: 600 },
]);
```

###### Remarks

Unit: milliseconds; must be zero or more. Paused time does not count, and the handle resolves once
the delayed burst has finished.

##### emission?

> `readonly` `optional` **emission?**: [`EmissionOptions`](#emissionoptions)

Emission Timing.

###### Default Value

`{ mode: "burst" }`

###### See

[EmissionOptions](#emissionoptions)

##### formation?

> `readonly` `optional` **formation?**: [`FormationOptions`](#formationoptions)

Formation.
The particles first form a text or an image, hold it, then burst apart. The shape is centered on
`origin`; `startVelocity` becomes the speed at which the particles fly outward, and `particleCount` (if
set) only caps the count the shape needs.

###### Default Value

```ts
none (a regular burst)
```

###### Example

```ts
Konfeti.fire({ formation: { text: "TEBRİKLER" }, origin: { x: 0.5, y: 0.4 } });
Konfeti.fire({ formation: { image: "/logo.png", mode: "appear", hold: 1500 } });
```

###### Remarks

Needs `emission: { mode: "burst" }` (the default). With `konfeti/lite`, call
`enableFormations()` once first.

###### See

[FormationOptions](#formationoptions)

##### lifetime?

> `readonly` `optional` **lifetime?**: [`Range`](#range)\<[`Milliseconds`](#milliseconds)\>

Particle Lifetime.
Particles are removed after this time (and earlier once they fall below the canvas, unless a floor is set).

###### Default Value

`[2800, 3600]`

##### origin?

> `readonly` `optional` **origin?**: [`Origin`](#origin)

Spawn Origin.

###### Default Value

`{ x: 0.5, y: 0.6 }`

###### See

[Origin](#origin)

##### paper?

> `readonly` `optional` **paper?**: [`PaperStyle`](#paperstyle)

Paper Style (and base style for every shape).

###### See

[PaperStyle](#paperstyle)

##### particleCount?

> `readonly` `optional` **particleCount?**: `number`

Number of Particles.
For `"interval"` emission this is per shot. Rounded down; negative values become `0`. Capped by the
instance's `maxParticles`.

###### Default Value

`60`

##### physics?

> `readonly` `optional` **physics?**: [`PhysicsOptions`](#physicsoptions)

Motion Physics.

###### See

[PhysicsOptions](#physicsoptions)

##### seed?

> `readonly` `optional` **seed?**: `number`

Random Seed.
The same seed with the same options and canvas size reproduces the exact same burst.

###### Default Value

```ts
random
```

##### shapes?

> `readonly` `optional` **shapes?**: readonly [`ShapeOptions`](#shapeoptions)[]

Shape Mix.
Each particle picks one entry (respecting `weight`). Omitted = paper only.

###### Default Value

`[{ type: "paper" }]`

###### Example

```ts
shapes: [
  { type: "paper", weight: 4 },
  { type: "star", colors: "gold" },
  { type: "emoji", emoji: ["🎉", "🥳"] },
]
```

###### See

[ShapeOptions](#shapeoptions)

##### spread?

> `readonly` `optional` **spread?**: [`Degrees`](#degrees)

Launch Cone Width.
Total opening angle around `angle`. `360` shoots in every direction.

###### Default Value

`60`

##### startVelocity?

> `readonly` `optional` **startVelocity?**: [`Range`](#range)\<[`PixelsPerSecond`](#pixelspersecond)\>

Launch Speed.
For a `formation`, the speed at which the particles burst apart from the shape.

###### Default Value

`[1000, 1800]` (`[300, 700]` with a `formation`)

#### Example

```ts
Konfeti.fire({
  particleCount: 120,
  angle: 60,
  spread: 55,
  origin: { x: 0, y: 0.7 },
  paper: { colors: ["#bb0000", "#ffffff"] },
  shapes: [{ type: "paper", weight: 3 }, { type: "emoji", emoji: "🎉" }],
});
```

***

### FlipAxis

> **FlipAxis** = `"x"` \| `"y"` \| `"both"`

3D Flip Axis.
- `"x"` — paper tumbles forward/backward (height squashes). The classic confetti look.
- `"y"` — paper turns left/right (width squashes).
- `"both"` — tumbles on both axes at slightly different speeds, for a chaotic flutter.

***

### FlipOptions

> **FlipOptions** = `object`

3D Flip Settings.
The flip squashes the paper along an axis and shows the back side (`backColor`) while it faces away.

#### Properties

##### axis?

> `readonly` `optional` **axis?**: [`FlipAxis`](#flipaxis)

Flip Axis.

###### Default Value

`"x"`

##### frequency?

> `readonly` `optional` **frequency?**: [`Range`](#range)\<[`Hertz`](#hertz)\>

Flip Speed.
Full turns per second. `1` flips the paper over and back once per second.

###### Default Value

`[0.6, 1.8]`

***

### FloorOptions

> **FloorOptions** = `object`

Floor Collision Settings.
Particles bounce off a horizontal line and then rest there until their lifetime ends.

#### Properties

##### bounce?

> `readonly` `optional` **bounce?**: [`Ratio`](#ratio)

Bounciness.
Fraction of vertical speed kept after a bounce. `0` = no bounce, `1` = perfectly elastic.

###### Default Value

`0.35`

##### friction?

> `readonly` `optional` **friction?**: [`Ratio`](#ratio)

Floor Friction.
Fraction of horizontal speed and spin lost per bounce.

###### Default Value

`0.4`

##### y?

> `readonly` `optional` **y?**: [`Ratio`](#ratio)

Floor Position.
Normalized canvas height (`1` = bottom edge).

###### Default Value

`1`

***

### FormationBase

> **FormationBase** = `object`

Settings Shared by Text and Image Formations.

#### See

[FormationOptions](#formationoptions)

#### Properties

##### assemble?

> `readonly` `optional` **assemble?**: [`Milliseconds`](#milliseconds)

Fly-In Duration.
How long `"assemble"` takes until the shape is complete. Particles set off with small random delays, so
the shape fills in organically; ignored by `"appear"`. Must be zero or more.

###### Default Value

`900`

###### Remarks

Unit: milliseconds.

##### easing?

> `readonly` `optional` **easing?**: [`Easing`](#easing-1)

Fly-In Easing.
How the particles move toward their places during `"assemble"`.

###### Default Value

`"easeOutCubic"` (fast start, soft landing)

###### See

[Easing](#easing-1)

##### fit?

> `readonly` `optional` **fit?**: [`Ratio`](#ratio)

Largest Share of the Canvas.
The whole formation (shape, spacing and particle size) is scaled down, never up, until it fits into this
share of the canvas width and height: a phone shows a smaller copy of the same picture, with the same
number of particles.

###### Default Value

`0.9`

###### Remarks

Unit: ratio of the canvas size, `0–1`; values outside are clamped to `0.05–1`.

##### hold?

> `readonly` `optional` **hold?**: [`Milliseconds`](#milliseconds)

Hold Time.
How long the finished shape stays on screen before the particles burst apart. Must be zero or more.

###### Default Value

`1000`

###### Remarks

Unit: milliseconds. The particles' `lifetime`, and every fade or change over life, starts when
they burst, so the shape stays fully visible until then. `fadeIn` has no effect on formations.

##### mode?

> `readonly` `optional` **mode?**: [`FormationMode`](#formationmode)

Start Mode.
`"assemble"` flies every particle in from beyond the canvas edges to its place in the shape; `"appear"`
shows the particles in the shape at once.

###### Default Value

`"assemble"`

###### Example

```ts
Konfeti.fire({ formation: { text: "WOW", mode: "appear", hold: 600 } });
```

###### See

[FormationMode](#formationmode)

##### spacing?

> `readonly` `optional` **spacing?**: [`Pixels`](#pixels)

Particle Spacing.
Distance between neighbouring particles in the shape: smaller is denser and easier to read, but needs
more particles. The particle count follows from it; an explicit `particleCount` only caps it. Must be a
positive number.

###### Default Value

`8`

###### Example

```ts
Konfeti.fire({ formation: { text: "OK", spacing: 6 } }); // denser letters
```

###### Remarks

Unit: pixels (CSS px), before `fit` scales the formation down. Halving the spacing roughly
quadruples the particle count; the instance's `maxParticles` still caps it, and the shape then thins out
evenly instead of losing a part.

***

### FormationMode

> **FormationMode** = `"assemble"` \| `"appear"`

How a Formation Starts.
- `"assemble"`: particles fly in from beyond the canvas edges and settle into the shape;
- `"appear"`: particles show up in the shape right away.

Either way the shape is held for `hold` milliseconds, then the particles burst apart.

***

### FormationOptions

> **FormationOptions** = [`TextFormation`](#textformation) \| [`ImageFormation`](#imageformation)

Formation Settings.
Particles first form a shape, text or an image, hold it, then burst apart. Set `text` or `image` (not
both); every shape type can take part, and the rest of the burst options apply as usual once the shape
breaks up: `startVelocity` becomes the speed at which particles fly outward from the shape's center.

#### Example

```ts
Konfeti.fire({
  origin: { x: 0.5, y: 0.4 }, // the center of the shape
  formation: { text: "TEBRİKLER", font: "900 110px sans-serif", hold: 1200 },
  shapes: [{ type: "paper", weight: 3 }, { type: "star" }],
});
Konfeti.fire({ formation: { image: "/logo.png", mode: "appear" }, startVelocity: [300, 600] });
```

#### Remarks

Needs `emission: { mode: "burst" }` (the default), and is not available for `emit()`. With
`konfeti/lite`, call `enableFormations()` once first.

#### See

 - [TextFormation](#textformation)
 - [ImageFormation](#imageformation)

***

### FrameRect

> **FrameRect** = `object`

Spritesheet Frame Rectangle in Source Pixels.

#### Properties

##### height

> `readonly` **height**: [`Pixels`](#pixels)

Frame Height.

##### width

> `readonly` **width**: [`Pixels`](#pixels)

Frame Width.

##### x

> `readonly` **x**: [`Pixels`](#pixels)

Left Edge.

##### y

> `readonly` **y**: [`Pixels`](#pixels)

Top Edge.

***

### FrameScheduler

> **FrameScheduler** = `object`

Animation Frame Scheduler.
Abstraction over `requestAnimationFrame`, mainly so tests can step frames manually.

#### Properties

##### cancel

> `readonly` **cancel**: (`id`) => `void`

Cancel Frame Request.

###### Parameters

###### id

`number`

Frame Request Id

###### Returns

`void`

##### request

> `readonly` **request**: (`callback`) => `number`

Request Next Frame.

###### Parameters

###### callback

(`time`) => `void`

Frame Callback receiving a high-resolution timestamp in milliseconds

###### Returns

`number`

Frame Request Id

***

### GradientOptions

> **GradientOptions** = `object`

Linear Gradient Fill.
Replaces the flat front color. The gradient is laid across the particle's own box, so it rotates, flips
and scales with the particle. The back side (when flipped) still uses `backColor`.

#### Example

```ts
paper: { gradient: { colors: ["#ffd700", "#ff8c00"], angle: 45 } }
```

#### Remarks

Creates one `CanvasGradient` per particle at spawn time (no per-frame cost).

#### Properties

##### angle?

> `readonly` `optional` **angle?**: [`Degrees`](#degrees)

Gradient Direction.
`0` runs left → right, `90` bottom → top.

###### Default Value

`90`

##### colors

> `readonly` **colors**: readonly \[[`ColorInput`](#colorinput), [`ColorInput`](#colorinput), `...ColorInput[]`\]

Gradient Color Stops.
At least two colors, spread evenly from start to end.

***

### HeartShapeOptions

> **HeartShapeOptions** = [`ShapeEntryBase`](#shapeentrybase) & `object`

Heart Shape Entry.

#### Type Declaration

##### size?

> `readonly` `optional` **size?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Heart Width.

###### Default Value

`[10, 16]`

##### type

> `readonly` **type**: `"heart"`

Shape Type.

***

### Hertz

> **Hertz** = `number`

Frequency in Cycles per Second.
`1` completes one full cycle (e.g. one full flip) every second.

***

### HexColor

> **HexColor** = `` `#${string}` ``

Hex Color String.
Supports `#rgb`, `#rgba`, `#rrggbb` and `#rrggbbaa`.

***

### HslColor

> **HslColor** = `` `hsl(${string})` `` \| `` `hsla(${string})` ``

HSL Color String.
Example: `hsl(210 100% 50%)` or `hsla(210, 100%, 50%, 0.8)`.

***

### ImageFormation

> **ImageFormation** = [`FormationBase`](#formationbase) & `object`

Formation Traced from an Image.
The opaque pixels of an image (a logo, an icon, a badge) become the shape, centered on the burst's
`origin`.

#### Type Declaration

##### font?

> `readonly` `optional` **font?**: `never`

Not Used by Image Formations.

##### image

> `readonly` **image**: [`ImageInput`](#imageinput)

Image.
A URL, inline `<svg>` markup, or any drawable image. Pixels at least half opaque belong to the shape.
The burst waits until the image has loaded; if it cannot be loaded or read, the burst ends without
particles.

###### Example

```ts
formation: { image: "/badge.png" }
formation: { image: '<svg width="100" height="100" viewBox="0 0 10 10"><circle cx="5" cy="5" r="5"/></svg>' }
```

###### Remarks

The pixels are read back from a canvas, so an image from another origin needs CORS headers.
Inline SVG markup is not supported by worker instances (browsers cannot decode SVG inside a worker).

##### imageColors?

> `readonly` `optional` **imageColors?**: `boolean`

Image Colors.
Paint each particle with the color of the pixel it sits on, so a colorful logo stays recognizable.
`false` keeps the shapes' own colors (the image then only gives the outline).

###### Default Value

`true`

###### Remarks

Only affects shapes drawn in a color (paper, vector shapes); emoji and images keep their look.
A shape `gradient` takes precedence, and `colorOverLife` does not apply to image-colored particles.

##### text?

> `readonly` `optional` **text?**: `never`

Not Used by Image Formations (set either `text` or `image`).

##### width?

> `readonly` `optional` **width?**: [`Pixels`](#pixels)

Width.
Size of the shape on screen before `fit` scales it down; the height follows the image's aspect ratio.

###### Default Value

```ts
the image's own width
```

###### Remarks

Unit: pixels (CSS px). Must be positive.

#### Example

```ts
await loadImage("/logo.png"); // optional: the burst waits for the image anyway
Konfeti.fire({ formation: { image: "/logo.png", width: 240 } });
```

***

### ImageInput

> **ImageInput** = `string` \| `CanvasImageSource`

Image Source.
A URL (loaded automatically; particles appear once it has loaded) or any drawable canvas image source.

***

### ImageShapeOptions

> **ImageShapeOptions** = [`ShapeEntryBase`](#shapeentrybase) & `object`

Image Shape Entry.
Draws images (logos, coins, stickers). Aspect ratio is preserved; `size` is the width. Colors only apply with
`tint`; stroke keys are ignored.

#### Type Declaration

##### size?

> `readonly` `optional` **size?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Rendered Width.

###### Default Value

`[16, 28]`

##### src

> `readonly` **src**: [`OneOrMany`](#oneormany)\<[`ImageInput`](#imageinput)\>

Image Source(s).
URLs are loaded automatically; particles become visible once loaded. Use `loadImage()` to preload. A string
starting with `<svg` is used as inline SVG markup — give the `<svg>` a `width` and `height` so it has a size.

###### Example

```ts
{ type: "image", src: '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24"><circle cx="12" cy="12" r="10" fill="gold"/></svg>' }
```

###### Remarks

Inline SVG is not supported by worker instances (browsers cannot decode SVG inside a worker).

##### tint?

> `readonly` `optional` **tint?**: `boolean` \| [`TintMode`](#tintmode)

Tint.
Recolors the image with the particle colors (`colors`, inherited from `paper.colors` when the entry sets none):
every particle picks a color the way a paper piece does and draws a copy of the image in that color. `true` is
`"multiply"` (keeps the shading, so white or grey artwork takes the colors best); `"fill"` gives flat silhouettes.

###### Default Value

`false` (the image keeps its own colors)

###### Example

```ts
shapes: [{ type: "image", src: "/coin-white.png", tint: true, colors: ["#ffd700", "#ff5e7e"] }]
shapes: [{ type: "image", src: "/logo.png", tint: "fill" }] // silhouettes in the paper colors
```

###### Remarks

Each color is painted once per image when it has loaded (at the largest size it is drawn, 256 px at most); drawing costs the same as without a tint.

###### See

[TintMode](#tintmode)

##### type

> `readonly` **type**: `"image"`

Shape Type.

#### Example

```ts
shapes: [{ type: "image", src: ["/coin.png", "/gem.png"], size: [20, 30], flip: false }]
```

***

### KonfetiEmitter

> **KonfetiEmitter** = `PromiseLike`\<`void`\> & `object`

Continuous Emitter Handle.
Returned by `emit()`. Awaiting it resolves once the emitter was stopped and its last particle is gone.

#### Type Declaration

##### clear()

> **clear**(): `void`

Stop and Remove Everything Now.
Ends the emitter and clears its particles immediately.

###### Returns

`void`

##### getParticleCount()

> **getParticleCount**(): `number`

Return Live Particle Count.

###### Returns

`number`

Particles Currently on Screen

##### isEmitting()

> **isEmitting**(): `boolean`

Check Whether It Still Creates Particles (false after stop() / clear()).

###### Returns

`boolean`

Emitting Flag

##### isFinished()

> **isFinished**(): `boolean`

Check Whether It Stopped and Every Particle Is Gone.

###### Returns

`boolean`

Finished Flag

##### isPaused()

> **isPaused**(): `boolean`

Check Whether pause() Is in Effect.

###### Returns

`boolean`

Paused Flag

##### moveTo()

> **moveTo**(`target`): `void`

Change What the Emitter Follows.

###### Parameters

###### target

[`EmitterTarget`](#emittertarget)

Element, `"pointer"` or Normalized Point

###### Returns

`void`

##### pause()

> **pause**(): `void`

Freeze the Emitter and Its Particles.

###### Returns

`void`

##### resume()

> **resume**(): `void`

Continue After pause().

###### Returns

`void`

##### stop()

> **stop**(): `void`

Stop Emitting.
No new particles are created; the ones already out keep flying until their lifetime ends.

###### Returns

`void`

#### Example

```ts
const fountain = Konfeti.emit({ rate: 40, follow: button });
fountain.moveTo("pointer"); // follow the pointer instead
fountain.stop();
await fountain; // every particle has finished
```

***

### KonfetiHandle

> **KonfetiHandle** = `PromiseLike`\<`void`\> & `object`

Burst Control Handle.
Returned by `fire()` (on `Konfeti` or any instance). Awaitable: resolves when every particle of the burst is gone (or it is stopped).

#### Type Declaration

##### getParticleCount()

> **getParticleCount**(): `number`

Return Live Particle Count.

###### Returns

`number`

Live Particle Count

##### getSeed()

> **getSeed**(): `number`

Return the Random Seed.
Fire the same options with this seed to get the same burst again: the same particles with the same
colors, sizes and launch values, and exactly the same motion on instances with `fixedTimestep`. For a
combined handle from `fire([...])`, the seed of the first burst (give each entry its own `seed` to replay
a list).

###### Returns

`number`

Seed

###### Example

```ts
const seed = Konfeti.fire().getSeed();
Konfeti.fire({ seed }); // the same burst again
```

##### isFinished()

> **isFinished**(): `boolean`

Return Finished State.

###### Returns

`boolean`

Finished State

##### isPaused()

> **isPaused**(): `boolean`

Return Paused State.

###### Returns

`boolean`

Paused State

##### pause()

> **pause**(): `void`

Freeze Burst in Place.
Particles stay visible but stop moving and aging.

###### Returns

`void`

##### resume()

> **resume**(): `void`

Resume Paused Burst.

###### Returns

`void`

##### stop()

> **stop**(): `void`

Remove Burst Immediately.
Clears its particles and resolves the handle.

###### Returns

`void`

#### Example

```ts
const burst = Konfeti.fire();
burst.pause();
setTimeout(() => burst.resume(), 500);
await burst; // finished
```

***

### KonfetiPaletteName

> **KonfetiPaletteName** = keyof *typeof* [`KonfetiPalettes`](#konfetipalettes)

Built-in Color Theme Name (`"PASTEL"`, `"GOLD"` …).

***

### KonfetiPresetName

> **KonfetiPresetName** = keyof *typeof* [`KonfetiPresets`](#konfetipresets)

Built-in Preset Name (`"SNOW"`, `"FIREWORKS"` …).

***

### Milliseconds

> **Milliseconds** = `number`

Duration in Milliseconds.

***

### ModernCssColor

> **ModernCssColor** = `` `hwb(${string})` `` \| `` `lab(${string})` `` \| `` `lch(${string})` `` \| `` `oklab(${string})` `` \| `` `oklch(${string})` `` \| `` `color(${string})` ``

Modern CSS Color Function String.
Parsed by the browser, so support depends on the user's browser.

***

### Multiplier

> **Multiplier** = `number`

Unitless Multiplier.
`1` keeps the original value, `2` doubles it, `0.5` halves it.

***

### MutableParticle

> **MutableParticle** = `{ -readonly [K in keyof ParticleState]: ParticleState[K] }`

Writable Particle Passed to `onParticleUpdate`.
Changing position/velocity here customizes motion per frame.

***

### OneOrMany

> **OneOrMany**\<`T`\> = `T` \| readonly (`T` \| [`Weighted`](#weighted)\<`T`\>)[]

Single Value or Weighted Pick List.
With a list, each particle picks one entry at random (respecting weights).

#### Type Parameters

##### T

`T`

#### Example

```ts
emoji: "🎉"
emoji: ["🎉", "🥳", { value: "✨", weight: 3 }]
```

***

### Origin

> **Origin** = [`OriginPoint`](#originpoint) \| `Element` \| [`ClientPoint`](#clientpoint)

Spawn Origin.
- [OriginPoint](#originpoint) — normalized canvas position (ranges spawn along a line/area).
- `Element` — the element's center, measured at every emission (follows moving elements).
- [ClientPoint](#clientpoint) — a viewport position, e.g. the click event itself.

#### Example

```ts
origin: { x: 0.5, y: 1 }
origin: document.querySelector("#buy-button")!
origin: clickEvent
```

***

### OriginPoint

> **OriginPoint** = `object`

Normalized Spawn Point.
`0,0` is the canvas' top-left corner, `1,1` its bottom-right. Ranges spawn along a line or inside an area.

#### Example

```ts
origin: { x: 0.5, y: 0.6 }            // slightly below center
origin: { x: [0, 1], y: 0 }            // anywhere along the top edge (snow)
```

#### Properties

##### x?

> `readonly` `optional` **x?**: [`Range`](#range)\<[`Ratio`](#ratio)\>

Horizontal Position.

###### Default Value

`0.5`

##### y?

> `readonly` `optional` **y?**: [`Range`](#range)\<[`Ratio`](#ratio)\>

Vertical Position.

###### Default Value

`0.6`

***

### PaperForm

> **PaperForm** = `"rect"` \| `"square"` \| `"circle"` \| `"strip"` \| `"leaf"`

Paper Silhouette.
- `"rect"` — rectangle using `width` × `height` (respects `cornerRadius`).
- `"square"` — like `"rect"`, but height always equals width.
- `"circle"` — ellipse filling `width` × `height` (a circle when both are equal).
- `"strip"` — pill shape: rectangle with fully rounded short ends. Looks best with a tall `height`.
- `"leaf"` — two opposite corners fully rounded (top-left and bottom-right), like a petal.

***

### PaperGeometry

> **PaperGeometry** = `object`

Paper-Only Geometry.

#### Properties

##### aspectRatio?

> `readonly` `optional` **aspectRatio?**: [`Range`](#range)\<[`Multiplier`](#multiplier)\>

Height-to-Width Ratio.
When set, height is `width × aspectRatio` instead of `height`. Values `≤ 0` are rejected.

###### Default Value

`undefined` (use `height`)

###### Example

```ts
paper: { width: [6, 12], aspectRatio: 1.6 }
```

##### cornerRadius?

> `readonly` `optional` **cornerRadius?**: [`CornerRadius`](#cornerradius)

Corner Radius.
Rounds `"rect"` and `"square"` corners. A number rounds all corners; an object sets each corner.
Clamped to half of the shorter side.

###### Default Value

`0`

###### Example

```ts
paper: { cornerRadius: 3 }
paper: { cornerRadius: { tl: 6, br: 6 } }
```

##### form?

> `readonly` `optional` **form?**: [`OneOrMany`](#oneormany)\<[`PaperForm`](#paperform)\>

Paper Silhouette(s).
A single form, or a list — each particle picks one (weights supported).

###### Default Value

`"rect"`

###### Example

```ts
paper: { form: ["rect", "circle", { value: "strip", weight: 2 }] }
```

###### See

[PaperForm](#paperform)

##### height?

> `readonly` `optional` **height?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Paper Height.
Ignored when `aspectRatio` is set or the picked form is `"square"`.

###### Default Value

`[10, 16]`

##### skew?

> `readonly` `optional` **skew?**: [`Range`](#range)\<[`Degrees`](#degrees)\>

Horizontal Skew.
Slants the piece into a parallelogram for a hand-cut look. Clamped to `-60…60`.

###### Default Value

`0`

##### width?

> `readonly` `optional` **width?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Paper Width.

###### Default Value

`[6, 10]`

***

### PaperShapeOptions

> **PaperShapeOptions** = [`ShapeEntryBase`](#shapeentrybase) & [`PaperGeometry`](#papergeometry) & `object`

Paper Shape Entry.
The default confetti piece. Geometry keys fall back to `paper`.

#### Type Declaration

##### type

> `readonly` **type**: `"paper"`

Shape Type.

#### Example

```ts
shapes: [{ type: "paper", form: "circle", weight: 2 }, { type: "star" }]
```

***

### PaperStyle

> **PaperStyle** = [`PaperGeometry`](#papergeometry) & [`ShapeStyle`](#shapestyle)

Default Paper Particle Style.
Paper geometry plus the common [ShapeStyle](#shapestyle). Its common style keys are also the base style for every
other shape in `shapes`.

#### Example

```ts
Konfeti.fire({
  paper: {
    form: ["rect", "circle"],
    colors: ["#ff0a54", "#ffd000", "#00c2ff"],
    cornerRadius: 2,
    stroke: { color: "white", width: 0.5 },
  },
});
```

***

### ParticleState

> **ParticleState** = `object`

Read-Only Particle Snapshot Passed to Hooks.
Positions are CSS pixels relative to the canvas, angles radians, times milliseconds.

#### Properties

##### age

> `readonly` **age**: `number`

Current Age.

##### frontColor

> `readonly` **frontColor**: `string`

Front Color (CSS string).

##### height

> `readonly` **height**: `number`

Current Height.

##### lifetime

> `readonly` **lifetime**: `number`

Total Lifetime.

##### rotation

> `readonly` **rotation**: `number`

2D Rotation in Radians.

##### vx

> `readonly` **vx**: `number`

Horizontal Velocity (px/s).

##### vy

> `readonly` **vy**: `number`

Vertical Velocity (px/s).

##### width

> `readonly` **width**: `number`

Current Width.

##### x

> `readonly` **x**: `number`

Horizontal Position.

##### y

> `readonly` **y**: `number`

Vertical Position.

***

### PathShapeDefinition

> **PathShapeDefinition**\<`TOptions`\> = `object`

Path-Based Custom Shape.
Return a path once per burst; the library fills, strokes, shades, flips and glints it like any built-in
vector shape (gradients, shine and stroke all work).

#### Example

```ts
defineShape("diamond", {
  viewBox: [24, 24],
  path: ({ sharpness = 0.5 }) => `M12 0 L${24 - sharpness * 12} 12 L12 24 L${sharpness * 12} 12 Z`,
});
```

#### Type Parameters

##### TOptions

`TOptions` *extends* `object`

#### Properties

##### defaultSize?

> `readonly` `optional` **defaultSize?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Size When the Entry Sets None.

###### Default Value

`[12, 18]`

##### path

> `readonly` **path**: (`options`) => `string` \| `Path2D`

Build the Path from Entry Options.
An SVG `d` string or a `Path2D`, in `viewBox` coordinates.

###### Parameters

###### options

`Readonly`\<`TOptions`\>

###### Returns

`string` \| `Path2D`

##### viewBox?

> `readonly` `optional` **viewBox?**: readonly \[`number`, `number`\]

Path Coordinate Box as `[width, height]`.

###### Default Value

`[24, 24]`

***

### PathShapeOptions

> **PathShapeOptions** = [`ShapeEntryBase`](#shapeentrybase) & `object`

Custom Vector Path Shape Entry.
Draws any SVG path (`d` attribute) or `Path2D`, filled with the particle color.

#### Type Declaration

##### path

> `readonly` **path**: [`OneOrMany`](#oneormany)\<`string` \| `Path2D`\>

SVG Path Data or Path2D.
A list picks one per particle.

##### size?

> `readonly` `optional` **size?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Rendered Size (longer side of the view box).

###### Default Value

`[12, 18]`

##### type

> `readonly` **type**: `"path"`

Shape Type.

##### viewBox?

> `readonly` `optional` **viewBox?**: readonly \[`number`, `number`\]

Path Coordinate Box as `[width, height]`.
The path is centered in this box and scaled so its longer side equals `size`.

###### Default Value

`[24, 24]`

#### Example

```ts
shapes: [{
  type: "path",
  path: "M12 2l3 7h7l-5.5 4 2 7-6.5-4.5L5.5 20l2-7L2 9h7z",
  viewBox: [24, 24],
}]
```

***

### PerSecond

> **PerSecond** = `number`

Exponential Decay Rate per Second.
Velocity is multiplied by `e^(-rate × seconds)`; `0` means no slowdown, higher values stop particles sooner.

***

### PhysicsDefinition

> **PhysicsDefinition**\<`TOptions`\> = `object`

Custom Physics Module Definition.
Enabled per burst with `physics: { <name>: true | { ...options } }`; `true` uses `defaults`.

#### Example

```ts
definePhysics("magnet", {
  defaults: { x: 0.5, y: 0.5, strength: 600 },
  apply: (p, dt, world, { x, y, strength }) => {
    p.vx += (x * world.width - p.x) * strength * dt * 0.001;
    p.vy += (y * world.height - p.y) * strength * dt * 0.001;
  },
});
```

#### Remarks

`apply` runs for every particle every frame — keep it allocation-free.

#### Type Parameters

##### TOptions

`TOptions` *extends* `object`

#### Properties

##### apply

> `readonly` **apply**: (`particle`, `dt`, `world`, `options`) => `void`

Apply Module to One Particle.

###### Parameters

###### particle

[`MutableParticle`](#mutableparticle)

###### dt

`number`

###### world

[`PhysicsWorldState`](#physicsworldstate)

###### options

`Readonly`\<`TOptions`\>

###### Returns

`void`

##### defaults

> `readonly` **defaults**: `Readonly`\<`TOptions`\>

Option Defaults (merged under the burst's options).

##### stage?

> `readonly` `optional` **stage?**: `"force"` \| `"constraint"`

Pipeline Stage.
`"force"` runs before positions update (change velocity), `"constraint"` after (clamp position).

###### Default Value

`"force"`

***

### PhysicsOptions

> **PhysicsOptions** = [`BuiltinPhysicsOptions`](#builtinphysicsoptions) & [`CustomPhysicsOptions`](#customphysicsoptions)

Motion Physics Settings (built-in keys plus registered custom modules).

***

### PhysicsWorldState

> **PhysicsWorldState** = `object`

Read-Only Simulation Bounds Passed to Custom Physics.

#### Properties

##### height

> `readonly` **height**: `number`

Canvas Height in CSS Pixels.

##### width

> `readonly` **width**: `number`

Canvas Width in CSS Pixels.

***

### Pixels

> **Pixels** = `number`

Length in CSS Pixels.
Measured before `devicePixelRatio` scaling, so `10` looks the same size on every screen.

***

### PixelsPerSecond

> **PixelsPerSecond** = `number`

Speed in CSS Pixels per Second.

***

### PixelsPerSecondSquared

> **PixelsPerSecondSquared** = `number`

Acceleration in CSS Pixels per Second Squared.

***

### PolygonShapeOptions

> **PolygonShapeOptions** = [`ShapeEntryBase`](#shapeentrybase) & `object`

Regular Polygon Shape Entry.

#### Type Declaration

##### sides?

> `readonly` `optional` **sides?**: [`Range`](#range)

Number of Sides.
Rounded to whole numbers, clamped to `3–12`.

###### Default Value

`6`

##### size?

> `readonly` `optional` **size?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Diameter.

###### Default Value

`[8, 14]`

##### type

> `readonly` **type**: `"polygon"`

Shape Type.

#### Example

```ts
shapes: [{ type: "polygon", sides: [5, 8] }]
```

***

### Range

> **Range**\<`T`\> = `T` \| [`RangeTuple`](#rangetuple)\<`T`\> \| [`RangeObject`](#rangeobject)\<`T`\>

Fixed Value or Random Range.
A plain number is used as-is. A tuple or object picks a uniformly random value between `min` and `max`
(inclusive) separately for every particle. If `min > max` the bounds are swapped.

#### Type Parameters

##### T

`T` *extends* `number` = `number`

#### Example

```ts
size: 10            // every particle is 10
size: [8, 14]       // each particle gets a random size between 8 and 14
size: { min: 8, max: 14 } // same as above
```

***

### RangeObject

> **RangeObject**\<`T`\> = `object`

Inclusive Range as `{ min, max }` Object.

#### Type Parameters

##### T

`T` *extends* `number` = `number`

#### Properties

##### max

> `readonly` **max**: `T`

Upper Bound.

##### min

> `readonly` **min**: `T`

Lower Bound.

***

### RangeTuple

> **RangeTuple**\<`T`\> = readonly \[`T`, `T`\]

Inclusive Range as `[min, max]` Tuple.

#### Type Parameters

##### T

`T` *extends* `number` = `number`

***

### Ratio

> **Ratio** = `number`

Normalized Value between `0` and `1`.
Values outside the range are clamped.

***

### RgbColor

> **RgbColor** = `` `rgb(${string})` `` \| `` `rgba(${string})` ``

RGB Color String.
Comma (`rgb(255, 0, 0)`) and space (`rgb(255 0 0 / 50%)`) syntax are both accepted.

***

### RibbonShapeOptions

> **RibbonShapeOptions** = [`ShapeEntryBase`](#shapeentrybase) & `object`

Curly Ribbon (Streamer) Shape Entry.
A long, wavy band — looks best with `flip: { axis: "y" }` and slower gravity.

#### Type Declaration

##### length?

> `readonly` `optional` **length?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Ribbon Length.

###### Default Value

`[18, 30]`

##### thickness?

> `readonly` `optional` **thickness?**: [`Ratio`](#ratio)

Band Thickness Relative to Length.

###### Default Value

`0.14`

##### type

> `readonly` **type**: `"ribbon"`

Shape Type.

##### waves?

> `readonly` `optional` **waves?**: `number`

Number of Curls.
Half sine waves along the length (whole numbers, `1–8`).

###### Default Value

`2`

#### Example

```ts
shapes: [{ type: "ribbon", length: [24, 40], waves: 3 }]
```

***

### ScaleOverLifeOptions

> **ScaleOverLifeOptions** = `object`

Size Transition over Lifetime.
Particles start at their normal size and scale toward `to` × size as they age.

#### Example

```ts
paper: { scaleOverLife: { to: 0, easing: "easeInCubic" } } // shrink away instead of fading
```

#### Properties

##### easing?

> `readonly` `optional` **easing?**: [`Easing`](#easing-1)

Transition Curve.

###### Default Value

`"linear"`

##### to

> `readonly` **to**: [`Multiplier`](#multiplier)

End Size Multiplier.
`0` shrinks to nothing, `2` doubles.

***

### ShadowOptions

> **ShadowOptions** = `object`

Drop Shadow.

#### Example

```ts
paper: { shadow: { color: "rgba(0,0,0,0.3)", blur: 4, offsetY: 2 } }
```

#### Remarks

Expensive: the browser blurs every shadowed particle again on every frame, and a larger `blur` costs
more (measured in Chrome: about 30 particles with `blur: 14` dropped the frame rate to about 40 fps). For
glowing particles prefer `blendMode: "lighter"` or an `image` shape with the glow drawn in, like the
`FIREFLIES` preset. `adaptiveQuality` turns shadows off on slow devices. Trails are drawn without the shadow.

#### Properties

##### blur?

> `readonly` `optional` **blur?**: [`Pixels`](#pixels)

Blur Radius.

###### Default Value

`4`

##### color?

> `readonly` `optional` **color?**: [`ColorInput`](#colorinput)

Shadow Color.

###### Default Value

`"rgba(0,0,0,0.25)"`

##### offsetX?

> `readonly` `optional` **offsetX?**: [`Pixels`](#pixels)

Horizontal Offset.

###### Default Value

`0`

##### offsetY?

> `readonly` `optional` **offsetY?**: [`Pixels`](#pixels)

Vertical Offset.

###### Default Value

`2`

***

### ShapeDefinition

> **ShapeDefinition**\<`TOptions`\> = [`PathShapeDefinition`](#pathshapedefinition)\<`TOptions`\> \| [`DrawShapeDefinition`](#drawshapedefinition)\<`TOptions`\>

Custom Shape Definition (path- or draw-based).

#### Type Parameters

##### TOptions

`TOptions` *extends* `object`

***

### ShapeEntryBase

> **ShapeEntryBase** = [`ShapeStyle`](#shapestyle) & `object`

Fields Shared by Every `shapes` Entry.
Style keys override the `paper` base style for this shape only.

#### Type Declaration

##### weight?

> `readonly` `optional` **weight?**: `number`

Relative Share of Particles.
With `shapes: [{ type: "star", weight: 3 }, { type: "paper" }]` three quarters of the particles are stars.
Must be `> 0`.

###### Default Value

`1`

***

### ShapeHandler

> **ShapeHandler**\<`TEntry`\> = `object`

Shape Handler.
Turns one `shapes[]` entry into a resolved, spawnable shape. Built-in handlers (`starShape`, `emojiShape` …)
are registered automatically by `konfeti`; with `konfeti/lite` register only the ones you use.

#### Type Parameters

##### TEntry

`TEntry` *extends* `object`

#### Properties

##### resolve

> `readonly` **resolve**: (`entry`, `context`) => `ResolvedShape`

Resolve Entry.

###### Parameters

###### entry

`TEntry`

###### context

[`ShapeHandlerContext`](#shapehandlercontext)

###### Returns

`ResolvedShape`

##### styleDefaults?

> `readonly` `optional` **styleDefaults?**: [`ShapeStyle`](#shapestyle)

Style Defaults for This Type (below `paper` and entry styles).

##### type

> `readonly` **type**: `TEntry`\[`"type"`\]

Handled Shape Type.

***

### ShapeHandlerContext

> **ShapeHandlerContext** = `object`

Context Passed to a Shape Handler while Resolving an Entry.

#### Properties

##### name

> `readonly` **name**: `string`

Option Path for Error Messages (e.g. `shapes[2]`).

##### paperLayers

> `readonly` **paperLayers**: readonly ([`PaperStyle`](#paperstyle) \| `undefined`)[]

Paper Option Layers (paper handler reads its geometry from them).

##### pixelRatio

> `readonly` **pixelRatio**: `number`

Canvas Pixel Ratio (bitmap raster resolution).

##### style

> `readonly` **style**: `ResolvedStyle`

Resolved Common Style (paper base + per-type defaults + entry overrides).

***

### ShapeOptions

> **ShapeOptions** = \[[`CustomShapeOptions`](#customshapeoptions)\] *extends* \[`never`\] ? [`BuiltinShapeOptions`](#builtinshapeoptions) : [`BuiltinShapeOptions`](#builtinshapeoptions) \| [`CustomShapeOptions`](#customshapeoptions)

Any `shapes` Entry (built-in or registered with `defineShape()`).
Discriminated by `type`; autocomplete shows the options of the chosen type only.

***

### ShapeStyle

> **ShapeStyle** = `object`

Common Particle Style.
Shared by every shape. Values set in `paper` also act as the base for all other shapes in `shapes`, so a
single `paper: { colors }` recolors stars, hearts and text too. Bitmap shapes (emoji, image, spritesheet)
ignore color and stroke keys.

#### Properties

##### backColor?

> `readonly` `optional` **backColor?**: [`ColorSource`](#colorsource) \| `"auto"`

Back Side Colors.
Shown while the 3D flip turns the particle away from the viewer. `"auto"` uses the front color darkened
by `backShade`. A color list picks independently of the front color.

###### Default Value

`"auto"`

###### Example

```ts
paper: { colors: "gold", backColor: "silver" }
```

##### backShade?

> `readonly` `optional` **backShade?**: [`Ratio`](#ratio)

Back Side Darkening.
How much darker the back side is when `backColor` is `"auto"`. `0` = same as front, `1` = black.

###### Default Value

`0.3`

##### blendMode?

> `readonly` `optional` **blendMode?**: `GlobalCompositeOperation`

Canvas Blend Mode.
For example `"lighter"` for glowing additive colors.

###### Default Value

`"source-over"`

##### colorMode?

> `readonly` `optional` **colorMode?**: [`ColorMode`](#colormode)

Color Pick Strategy.

###### Default Value

`"random"`

###### See

[ColorMode](#colormode)

##### colorOverLife?

> `readonly` `optional` **colorOverLife?**: [`ColorOverLifeOptions`](#coloroverlifeoptions) \| `false`

Color Transition over Lifetime.
`false` (or omitted) keeps the color constant.

###### Default Value

`false`

###### See

[ColorOverLifeOptions](#coloroverlifeoptions)

##### colors?

> `readonly` `optional` **colors?**: [`ColorSource`](#colorsource)

Front Colors.

###### Default Value

`["#26ccff", "#a25afd", "#ff5e7e", "#88ff5a", "#fcff42", "#ffa62d", "#ff36ff"]`

###### See

[ColorSource](#colorsource)

##### fadeIn?

> `readonly` `optional` **fadeIn?**: [`Ratio`](#ratio)

Fade-In Duration.
Fraction of the lifetime spent fading in from transparent. `0` appears instantly.

###### Default Value

`0`

##### fadeOut?

> `readonly` `optional` **fadeOut?**: `boolean` \| [`FadeOutOptions`](#fadeoutoptions)

Fade Out near End of Life.
`true` uses the default fade, `false` keeps particles opaque until they disappear, an object customizes it.

###### Default Value

`{ start: 0.7, easing: "linear" }`

###### See

[FadeOutOptions](#fadeoutoptions)

##### flip?

> `readonly` `optional` **flip?**: `boolean` \| [`FlipOptions`](#flipoptions)

3D Flip.
`true` uses the default flip, `false` keeps the particle flat, an object customizes it.

###### Default Value

`{ frequency: [0.6, 1.8], axis: "x" }`

###### See

[FlipOptions](#flipoptions)

##### gradient?

> `readonly` `optional` **gradient?**: [`GradientOptions`](#gradientoptions) \| `false`

Gradient Fill.
`false` (or omitted) uses flat colors.

###### Default Value

`false`

###### See

[GradientOptions](#gradientoptions)

##### opacity?

> `readonly` `optional` **opacity?**: [`Range`](#range)\<[`Ratio`](#ratio)\>

Starting Opacity.
`1` is fully opaque, `0` is invisible.

###### Default Value

`1`

##### rotation?

> `readonly` `optional` **rotation?**: [`Range`](#range)\<[`Degrees`](#degrees)\>

Initial Rotation.

###### Default Value

`[0, 360]`

##### rotationSpeed?

> `readonly` `optional` **rotationSpeed?**: [`Range`](#range)\<[`DegreesPerSecond`](#degreespersecond)\>

Spin Speed.
Negative values spin counter-clockwise.

###### Default Value

`[-240, 240]`

##### scale?

> `readonly` `optional` **scale?**: [`Range`](#range)\<[`Multiplier`](#multiplier)\>

Uniform Size Multiplier.
Scales every size-related value (size, width, height, radius, stroke) together.

###### Default Value

`1`

##### scaleOverLife?

> `readonly` `optional` **scaleOverLife?**: [`ScaleOverLifeOptions`](#scaleoverlifeoptions) \| `false`

Size Transition over Lifetime.
`false` (or omitted) keeps the size constant.

###### Default Value

`false`

###### See

[ScaleOverLifeOptions](#scaleoverlifeoptions)

##### shadow?

> `readonly` `optional` **shadow?**: [`ShadowOptions`](#shadowoptions) \| `false`

Drop Shadow.
`false` (or omitted) draws no shadow.

###### Default Value

`false`

###### See

[ShadowOptions](#shadowoptions)

##### shine?

> `readonly` `optional` **shine?**: [`Ratio`](#ratio)

Specular Shine.
Brightens the particle while it faces the viewer during the flip. `0` disables it, `1` is a strong glint.
Only visible when `flip` is enabled; ignored by emoji, image and spritesheet shapes.

###### Default Value

`0`

###### Remarks

Costs one extra fill per visible particle.

##### stroke?

> `readonly` `optional` **stroke?**: [`StrokeOptions`](#strokeoptions) \| `false`

Outline.
`false` (or omitted) draws no outline.

###### Default Value

`false`

###### Remarks

Stroking costs roughly one extra draw call per particle.

##### tilt?

> `readonly` `optional` **tilt?**: [`Range`](#range)\<[`Degrees`](#degrees)\>

Perspective Tilt.
Maximum oscillating skew, synced to the wobble, that makes flat pieces look like they catch the air.
`0` disables it.

###### Default Value

`0`

###### Example

```ts
paper: { tilt: 25 }
```

##### trail?

> `readonly` `optional` **trail?**: `boolean` \| [`TrailOptions`](#trailoptions)

Motion Trail.
`true` draws the default streak behind each particle, `false` disables it, an object sets length, width,
opacity and color.

###### Default Value

`false`

###### Example

```ts
Konfeti.fire({ paper: { trail: { length: 14, color: "#ffd000" } } });
```

###### Remarks

Costs about one extra draw call per trail point per particle.

###### See

[TrailOptions](#trailoptions)

##### wobble?

> `readonly` `optional` **wobble?**: `boolean` \| [`WobbleOptions`](#wobbleoptions)

Side-to-Side Flutter.
`true` uses the default wobble, `false` disables it, an object customizes it.

###### Default Value

`{ amplitude: [2, 8], frequency: [0.4, 1.2] }`

###### See

[WobbleOptions](#wobbleoptions)

***

### ShapeType

> **ShapeType** = [`ShapeOptions`](#shapeoptions)\[`"type"`\]

Shape Type Name.

***

### SharedKonfeti

> **SharedKonfeti** = `Pick`\<[`KonfetiInstance`](#konfetiinstance), `"fire"` \| `"emit"` \| `"onClick"` \| `"pause"` \| `"resume"` \| `"isPaused"` \| `"reset"` \| `"getParticleCount"`\>

Shared Fullscreen Konfeti.
The `Konfeti` object: the everyday API, drawing on a fullscreen overlay canvas that is created on the first
`Konfeti.fire()`. Use `KonfetiFactory.create()` for your own canvas or separate defaults.

***

### SpriteAtlas

> **SpriteAtlas** = `object`

Sprite Atlas JSON.
The frame list a sprite packer exports next to the sheet image (TexturePacker, Aseprite, Free Texture Packer,
Phaser). Both layouts are accepted: "JSON Hash" (`frames` keyed by frame name) and "JSON Array" (`frames` as a list
with a `filename` each). Other fields (`meta`, `sourceSize`, `duration` …) are ignored.

#### Example

```json
{ "frames": { "coin_0.png": { "frame": { "x": 0, "y": 0, "w": 32, "h": 32 } } }, "meta": { "image": "coins.png" } }
```

#### Properties

##### frames

> `readonly` **frames**: `Readonly`\<`Record`\<`string`, [`SpriteAtlasFrame`](#spriteatlasframe)\>\> \| readonly [`SpriteAtlasFrame`](#spriteatlasframe)[]

Frames, Keyed by Name or Listed.

***

### SpriteAtlasFrame

> **SpriteAtlasFrame** = `object`

One Frame of a Sprite Atlas JSON.
The shape TexturePacker, Aseprite, Free Texture Packer and Phaser write: the frame's rectangle in the sheet, and
flags for frames the packer rotated or trimmed.

#### Properties

##### filename?

> `readonly` `optional` **filename?**: `string`

Frame Name (the "JSON Array" layout; the "JSON Hash" layout keys frames by name instead).

##### frame

> `readonly` **frame**: `object`

Frame Rectangle in the Sheet (source pixels).

###### h

> `readonly` **h**: `number`

Height.

###### w

> `readonly` **w**: `number`

Width.

###### x

> `readonly` **x**: `number`

Left Edge.

###### y

> `readonly` **y**: `number`

Top Edge.

##### rotated?

> `readonly` `optional` **rotated?**: `boolean`

Rotated by the Packer (not supported: export the sheet without rotation).

##### trimmed?

> `readonly` `optional` **trimmed?**: `boolean`

Trimmed by the Packer (frames of different sizes are each stretched to the particle size).

***

### SpriteFrames

> **SpriteFrames** = \{ `cols`: `number`; `count?`: `number`; `rows`: `number`; \} \| readonly [`FrameRect`](#framerect)[]

Spritesheet Frame Layout.
- Grid: frames of equal size, read left → right, top → bottom. `count` limits the frames used when the last
  row is not full.
- Rect list: explicit frame rectangles (e.g. from an atlas JSON), played in order.

#### Union Members

##### Type Literal

\{ `cols`: `number`; `count?`: `number`; `rows`: `number`; \}

###### cols

> `readonly` **cols**: `number`

Column Count.

###### count?

> `readonly` `optional` **count?**: `number`

Used Frame Count.

###### Default Value

`cols × rows`

###### rows

> `readonly` **rows**: `number`

Row Count.

***

readonly [`FrameRect`](#framerect)[]

#### Example

```ts
frames: { cols: 8, rows: 1 }
frames: { cols: 4, rows: 4, count: 14 }
frames: [{ x: 0, y: 0, width: 32, height: 32 }, { x: 32, y: 0, width: 32, height: 32 }]
```

***

### SpriteSheetShapeOptions

> **SpriteSheetShapeOptions** = [`ShapeEntryBase`](#shapeentrybase) & `object`

Animated Spritesheet Shape Entry.
Plays frames from one image, e.g. a spinning coin. `size` is the rendered frame width.

#### Type Declaration

##### fps?

> `readonly` `optional` **fps?**: [`Range`](#range)

Playback Speed in Frames per Second.

###### Default Value

`12`

##### frames

> `readonly` **frames**: [`SpriteFrames`](#spriteframes)

Frame Layout.

###### See

[SpriteFrames](#spriteframes)

##### loop?

> `readonly` `optional` **loop?**: `boolean`

Loop Playback.
When `false`, the animation holds its last frame.

###### Default Value

`true`

##### randomStartFrame?

> `readonly` `optional` **randomStartFrame?**: `boolean`

Random Start Frame.
Desynchronizes particles so they don't all animate in lockstep.

###### Default Value

`true`

##### size?

> `readonly` `optional` **size?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Rendered Frame Width.

###### Default Value

`[16, 28]`

##### src

> `readonly` **src**: [`ImageInput`](#imageinput)

Spritesheet Image.
A URL, any canvas image source, or inline `<svg>` markup (give the `<svg>` a `width` and `height`).

##### tint?

> `readonly` `optional` **tint?**: `boolean` \| [`TintMode`](#tintmode)

Tint.
Recolors the sheet with the particle colors (`colors`, inherited from `paper.colors` when the entry sets none):
every particle picks a color the way a paper piece does and draws a copy of the sheet in that color. `true` is
`"multiply"` (keeps the shading, so white or grey artwork takes the colors best); `"fill"` gives flat silhouettes.

###### Default Value

`false` (the sheet keeps its own colors)

###### Example

```ts
shapes: [{ type: "spritesheet", src: "/coin-white.png", frames: { cols: 8, rows: 1 }, tint: true, colors: ["#ffd700", "#ff5e7e"] }]
shapes: [{ type: "spritesheet", src: "/logo.png", frames: { cols: 8, rows: 1 }, tint: "fill" }] // silhouettes in the paper colors
```

###### Remarks

Each color is painted once per sheet when it has loaded (at its own size, so the frames stay in place); drawing costs the same as without a tint.

###### See

[TintMode](#tintmode)

##### type

> `readonly` **type**: `"spritesheet"`

Shape Type.

#### Example

```ts
shapes: [{
  type: "spritesheet",
  src: "/coin-spin.png",
  frames: { cols: 8, rows: 1 },
  fps: [12, 18],
  flip: false,
}]
```

***

### StarShapeOptions

> **StarShapeOptions** = [`ShapeEntryBase`](#shapeentrybase) & `object`

Star Shape Entry.

#### Type Declaration

##### innerRatio?

> `readonly` `optional` **innerRatio?**: [`Ratio`](#ratio)

Inner Radius Ratio.
Inner point distance relative to the outer radius. Lower = spikier.

###### Default Value

`0.5`

##### points?

> `readonly` `optional` **points?**: [`Range`](#range)

Number of Points.
Rounded to whole numbers, clamped to `3–12`. A range mixes star types.

###### Default Value

`5`

##### size?

> `readonly` `optional` **size?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Outer Diameter.

###### Default Value

`[10, 16]`

##### type

> `readonly` **type**: `"star"`

Shape Type.

#### Example

```ts
shapes: [{ type: "star", points: [5, 6], innerRatio: 0.45, colors: ["gold", "#fff3b0"] }]
```

***

### StrokeOptions

> **StrokeOptions** = `object`

Outline Settings.

#### Properties

##### color

> `readonly` **color**: [`ColorInput`](#colorinput)

Outline Color.

###### Example

```ts
stroke: { color: "white", width: 1 }
```

##### width?

> `readonly` `optional` **width?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Outline Thickness.
In particle-local pixels, so the outline scales with `scale` and squashes with the 3D flip.

###### Default Value

`1`

***

### SwirlOptions

> **SwirlOptions** = `object`

Swirl Settings.
Adds a rotating push to each particle so it drifts in loops, like leaves in a breeze.

#### Properties

##### frequency?

> `readonly` `optional` **frequency?**: [`Range`](#range)\<[`Hertz`](#hertz)\>

Loop Speed.

###### Default Value

`[0.3, 0.8]`

##### strength?

> `readonly` `optional` **strength?**: [`Range`](#range)\<[`PixelsPerSecondSquared`](#pixelspersecondsquared)\>

Push Strength.

###### Default Value

`[80, 200]`

***

### TextFormation

> **TextFormation** = [`FormationBase`](#formationbase) & `object`

Formation Spelled from Text.
The particles spell a word or a short message, centered on the burst's `origin`.

#### Type Declaration

##### font?

> `readonly` `optional` **font?**: `string`

Font.
A CSS font shorthand (`weight size family`). Heavy weights read best, since the particles fill the
letter strokes.

###### Default Value

`"900 96px sans-serif"`

###### Example

```ts
formation: { text: "GO!", font: "bold 140px 'Luckiest Guy'" }
```

###### Remarks

The size is the size on screen before `fit` scales the shape down. A web font that is still
loading is waited for (through `document.fonts`). Worker instances only see fonts the worker itself
knows: system fonts, or a `FontFace` loaded inside the worker.

##### image?

> `readonly` `optional` **image?**: `never`

Not Used by Text Formations (set either `text` or `image`).

##### imageColors?

> `readonly` `optional` **imageColors?**: `never`

Not Used by Text Formations (particles keep their own colors).

##### text

> `readonly` **text**: `string`

Text.
What the particles spell. `\n` starts a new line; lines are centered. Must not be empty.

###### Example

```ts
formation: { text: "LEVEL\nUP" }
```

##### width?

> `readonly` `optional` **width?**: `never`

Not Used by Text Formations (the font size sets the size).

#### Example

```ts
Konfeti.fire({ formation: { text: "TEBRİKLER", font: "900 120px Inter" } });
Konfeti.fire({ formation: { text: "YOU\nWIN", mode: "appear", hold: 1500 } }); // two lines
```

***

### TextShapeOptions

> **TextShapeOptions** = [`ShapeEntryBase`](#shapeentrybase) & `object`

Text Shape Entry.
Words or letters filled with the particle colors (one cached bitmap per text × color).

#### Type Declaration

##### fontFamily?

> `readonly` `optional` **fontFamily?**: `string`

Font Family.
Make sure web fonts are loaded before firing (`document.fonts.ready`).

###### Default Value

`"system-ui, sans-serif"`

##### fontWeight?

> `readonly` `optional` **fontWeight?**: `number` \| `"normal"` \| `"bold"`

Font Weight.

###### Default Value

`700`

##### size?

> `readonly` `optional` **size?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Font Size.

###### Default Value

`[14, 22]`

##### text

> `readonly` **text**: [`OneOrMany`](#oneormany)\<`string`\>

Text Content(s).

##### type

> `readonly` **type**: `"text"`

Shape Type.

#### Example

```ts
shapes: [{ type: "text", text: ["YAY", "WOW"], fontWeight: 900, colors: ["#ff0a54", "#00c2ff"] }]
```

***

### TintMode

> **TintMode** = `"multiply"` \| `"fill"`

How a Tint Recolors an Image.
- `"multiply"` — multiplies the color into the image and keeps its shading: white turns fully into the color, black
  stays black, greys become darker shades of it.
- `"fill"` — a flat silhouette: every visible pixel takes the color, keeping its transparency.

***

### TrailOptions

> **TrailOptions** = `object`

Motion Trail Settings.
Draws a short streak behind each particle through its last positions, thinning and fading toward the tail —
sparks, comets, fireworks.

#### Example

```ts
Konfeti.fire({ paper: { trail: true } });
Konfeti.fire({ shapes: [{ type: "star", trail: { length: 16, width: 4, color: "gold" } }] });
```

#### Remarks

Each trail segment is one stroke: `length` 10 costs about 10 extra draw calls per particle. Keep
`length` modest for large bursts.

#### Properties

##### color?

> `readonly` `optional` **color?**: [`ColorInput`](#colorinput) \| `"particle"`

Trail Color.
`"particle"` uses each particle's own (front) color.

###### Default Value

`"particle"`

##### length?

> `readonly` `optional` **length?**: `number`

Trail Length.
How many recent positions (one per frame) the trail runs through. Clamped to 2–32.

###### Default Value

`10`

##### opacity?

> `readonly` `optional` **opacity?**: [`Ratio`](#ratio)

Head Opacity.
Opacity right behind the particle, fading to transparent at the tail. It is multiplied by the particle's own
fade, so trails vanish with their particle. Clamped to 0–1.

###### Default Value

`0.5`

##### width?

> `readonly` `optional` **width?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Head Width.
Line width right behind the particle; the trail tapers to nothing at its tail.

###### Default Value

`3`

###### Remarks

Unit: pixels (CSS px).

***

### TriangleShapeOptions

> **TriangleShapeOptions** = [`ShapeEntryBase`](#shapeentrybase) & `object`

Triangle Shape Entry.
Equilateral triangle.

#### Type Declaration

##### size?

> `readonly` `optional` **size?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Side Length.

###### Default Value

`[8, 14]`

##### type

> `readonly` **type**: `"triangle"`

Shape Type.

***

### Weighted

> **Weighted**\<`T`\> = `object`

Value with Pick Weight.
Used in lists to make some entries appear more often. Plain (non-weighted) entries count as weight `1`.

#### Example

```ts
form: ["rect", { value: "circle", weight: 3 }] // circles are 3× as common as rects
```

#### Type Parameters

##### T

`T`

#### Properties

##### value

> `readonly` **value**: `T`

Entry Value.

##### weight

> `readonly` **weight**: `number`

Relative Pick Weight.
Must be `> 0`.

###### Default Value

`1`

***

### WeightedColor

> **WeightedColor** = `object`

Color with Pick Weight.
Used inside a color list to make some colors appear more often than others.

#### Example

```ts
colors: [{ color: "gold", weight: 3 }, "white"] // gold is picked 3× as often as white
```

#### Properties

##### color

> `readonly` **color**: [`ColorInput`](#colorinput)

Color Value.

##### weight

> `readonly` **weight**: `number`

Relative Pick Weight.
Must be `> 0`. Plain (non-weighted) colors in the same list count as weight `1`.

###### Default Value

`1`

***

### WobbleOptions

> **WobbleOptions** = `object`

Side-to-Side Flutter Settings.
Adds a sinusoidal horizontal sway on top of the physical motion, like paper drifting through air.

#### Properties

##### amplitude?

> `readonly` `optional` **amplitude?**: [`Range`](#range)\<[`Pixels`](#pixels)\>

Sway Distance.
Maximum horizontal offset from the particle's physical path.

###### Default Value

`[2, 8]`

##### frequency?

> `readonly` `optional` **frequency?**: [`Range`](#range)\<[`Hertz`](#hertz)\>

Sway Speed.
Full left-right-left cycles per second.

###### Default Value

`[0.4, 1.2]`

## Variables

### emojiShape

> `const` **emojiShape**: [`ShapeHandler`](#shapehandler)\<[`EmojiShapeOptions`](#emojishapeoptions)\>

Emoji Shape Handler.

***

### heartShape

> `const` **heartShape**: [`ShapeHandler`](#shapehandler)\<[`HeartShapeOptions`](#heartshapeoptions)\>

Heart Shape Handler.

***

### imageShape

> `const` **imageShape**: [`ShapeHandler`](#shapehandler)\<[`ImageShapeOptions`](#imageshapeoptions)\>

Image Shape Handler.

***

### Konfeti

> `const` **Konfeti**: [`SharedKonfeti`](#sharedkonfeti)

Shared Fullscreen Konfeti.
Every call goes to one lazily created fullscreen instance, so importing is SSR-safe and nothing touches the
DOM until the first `Konfeti.fire()`.

#### Example

```ts
import { Konfeti, KonfetiPresets } from "konfeti";

Konfeti.fire();
await Konfeti.fire({ particleCount: 150, spread: 90, paper: { colors: ["gold", "white"] } });
Konfeti.fire(KonfetiPresets.FIREWORKS);
Konfeti.onClick(document.querySelector("#like")!, { particleCount: 30 });
Konfeti.reset();
```

***

### KonfetiPalettes

> `const` **KonfetiPalettes**: `object`

Built-in Color Themes.
Ready-made color lists for `colors` (on `paper` or any shape), one per member. Plain read-only data: use one
as is, mix two, or spread one into your own list.

#### Type Declaration

##### AUTUMN

> `readonly` **AUTUMN**: readonly \[`"#d35400"`, `"#e67e22"`, `"#f1c40f"`, `"#a0522d"`, `"#8b0000"`, `"#c0392b"`\]

Autumn.
Burnt orange, amber, rust and deep red — falling leaves (try `form: "leaf"`).

##### CANDY

> `readonly` **CANDY**: readonly \[`"#ff6fb5"`, `"#ff9ecd"`, `"#b5a2ff"`, `"#7ee8fa"`, `"#fff47d"`, `"#ffb86f"`\]

Candy.
Sweet pinks, lilac, mint and lemon.

##### CLASSIC

> `readonly` **CLASSIC**: readonly \[`"#26ccff"`, `"#a25afd"`, `"#ff5e7e"`, `"#88ff5a"`, `"#fcff42"`, `"#ffa62d"`, `"#ff36ff"`\]

Classic.
The library's default mix of bright confetti colors.

##### FOREST

> `readonly` **FOREST**: readonly \[`"#1b4332"`, `"#2d6a4f"`, `"#40916c"`, `"#74c69d"`, `"#b7e4c7"`, `"#8b5a2b"`\]

Forest.
Greens from pine to lime, with a touch of bark brown.

##### GOLD

> `readonly` **GOLD**: readonly \[`"#ffd700"`, `"#ffcc33"`, `"#f5b700"`, `"#e6be8a"`, `"#fff1b8"`, `"#c9a227"`\]

Gold.
Warm golds and champagne for awards, anniversaries and "premium" moments.

##### MONOCHROME

> `readonly` **MONOCHROME**: readonly \[`"#ffffff"`, `"#e5e5e5"`, `"#bdbdbd"`, `"#8a8a8a"`, `"#4d4d4d"`\]

Monochrome.
White to charcoal grays — elegant on colored backgrounds.

##### NEON

> `readonly` **NEON**: readonly \[`"#39ff14"`, `"#ff073a"`, `"#00f0ff"`, `"#ff00ff"`, `"#fff01f"`, `"#ff6ec7"`\]

Neon.
Saturated glowing colors; pair with `blendMode: "lighter"` on dark backgrounds.

##### OCEAN

> `readonly` **OCEAN**: readonly \[`"#006994"`, `"#0096c7"`, `"#48cae4"`, `"#90e0ef"`, `"#caf0f8"`, `"#00b4d8"`\]

Ocean.
Deep to pale blues and teals.

##### PASTEL

> `readonly` **PASTEL**: readonly \[`"#ffd1dc"`, `"#ffe4b5"`, `"#fffacd"`, `"#d4f0c0"`, `"#c1e1ff"`, `"#e0c3fc"`\]

Pastel.
Soft, light tints for baby showers, weddings and calm celebrations.

##### RAINBOW

> `readonly` **RAINBOW**: readonly \[`"#ff0000"`, `"#ff8000"`, `"#ffff00"`, `"#00c000"`, `"#0080ff"`, `"#8000ff"`\]

Rainbow.
The six spectrum colors in order (try `colorMode: "sequence"`).

##### WINTER

> `readonly` **WINTER**: readonly \[`"#ffffff"`, `"#e8f4ff"`, `"#b3dcff"`, `"#7fb8e6"`, `"#c0c0c0"`\]

Winter.
Whites, ice blues and silver for snow and holiday scenes.

#### Example

```ts
import { Konfeti, KonfetiPalettes } from "konfeti";

Konfeti.fire({ paper: { colors: KonfetiPalettes.PASTEL } });
Konfeti.fire({ paper: { colors: [...KonfetiPalettes.GOLD, "#ffffff"] } });
Konfeti.fire({ shapes: [{ type: "star", colors: KonfetiPalettes.NEON }] });
```

***

### KonfetiPresets

> `const` **KonfetiPresets**: `object`

Built-in Presets.
Ready-to-fire options, one per member. Every preset is plain, read-only data: pass it to `fire()` as is,
inspect it, or combine it with your own settings through [extendPreset](#extendpreset).

#### Type Declaration

##### BASIC

> `readonly` **BASIC**: `object` = `{}`

Basic.
The library defaults: one classic confetti pop, upward from just below the screen center.

##### CANNON

> `readonly` **CANNON**: `object`

Cannon.
A fast, narrow shot from the bottom-left corner towards the upper right.

###### CANNON.angle

> `readonly` **angle**: `60` = `60`

###### CANNON.origin

> `readonly` **origin**: `object`

###### CANNON.origin.x

> `readonly` **x**: `0` = `0`

###### CANNON.origin.y

> `readonly` **y**: `0.8` = `0.8`

###### CANNON.particleCount

> `readonly` **particleCount**: `100` = `100`

###### CANNON.spread

> `readonly` **spread**: `45` = `45`

###### CANNON.startVelocity

> `readonly` **startVelocity**: readonly \[`1600`, `2400`\]

##### CONGRATS

> `readonly` **CONGRATS**: `object`

Congrats.
Paper and stars fly in from beyond the edges to spell "CONGRATS!", hold it, then burst apart (shows a text
`formation`).

###### CONGRATS.formation

> `readonly` **formation**: `object`

###### CONGRATS.formation.font

> `readonly` **font**: `"900 120px sans-serif"` = `"900 120px sans-serif"`

###### CONGRATS.formation.hold

> `readonly` **hold**: `1200` = `1200`

###### CONGRATS.formation.text

> `readonly` **text**: `"CONGRATS!"` = `"CONGRATS!"`

###### CONGRATS.origin

> `readonly` **origin**: `object`

###### CONGRATS.origin.x

> `readonly` **x**: `0.5` = `0.5`

###### CONGRATS.origin.y

> `readonly` **y**: `0.42` = `0.42`

###### CONGRATS.shapes

> `readonly` **shapes**: readonly \[\{ `type`: `"paper"`; `weight`: `4`; \}, \{ `colors`: readonly \[`"#ffe400"`, `"#ffbd00"`, `"#fdffb8"`\]; `size`: readonly \[`9`, `13`\]; `type`: `"star"`; \}\]

##### EMOJI\_RAIN

> `readonly` **EMOJI\_RAIN**: `object`

Emoji Rain.
Party emoji falling from the top edge for three seconds.

###### EMOJI\_RAIN.angle

> `readonly` **angle**: `270` = `270`

###### EMOJI\_RAIN.emission

> `readonly` **emission**: `object`

###### EMOJI\_RAIN.emission.duration

> `readonly` **duration**: `3000` = `3000`

###### EMOJI\_RAIN.emission.mode

> `readonly` **mode**: `"stream"` = `"stream"`

###### EMOJI\_RAIN.lifetime

> `readonly` **lifetime**: readonly \[`3000`, `4000`\]

###### EMOJI\_RAIN.origin

> `readonly` **origin**: `object`

###### EMOJI\_RAIN.origin.x

> `readonly` **x**: readonly \[`0`, `1`\]

###### EMOJI\_RAIN.origin.y

> `readonly` **y**: `-0.05` = `-0.05`

###### EMOJI\_RAIN.particleCount

> `readonly` **particleCount**: `60` = `60`

###### EMOJI\_RAIN.physics

> `readonly` **physics**: `object`

###### EMOJI\_RAIN.physics.drag

> `readonly` **drag**: `1.2` = `1.2`

###### EMOJI\_RAIN.physics.gravity

> `readonly` **gravity**: `400` = `400`

###### EMOJI\_RAIN.shapes

> `readonly` **shapes**: readonly \[\{ `emoji`: readonly \[`"🎉"`, `"🥳"`, `"🎊"`, `"✨"`\]; `size`: readonly \[`22`, `34`\]; `type`: `"emoji"`; \}\]

###### EMOJI\_RAIN.spread

> `readonly` **spread**: `20` = `20`

###### EMOJI\_RAIN.startVelocity

> `readonly` **startVelocity**: readonly \[`100`, `300`\]

##### FIREFLIES

> `readonly` **FIREFLIES**: `object`

Fireflies.
Glowing dots appear over the lower part of the canvas, drift and wander slowly, then fade (made for dark
backgrounds; each firefly is a small glow PNG data URL, so it also works in worker instances).

###### FIREFLIES.emission

> `readonly` **emission**: `object`

###### FIREFLIES.emission.duration

> `readonly` **duration**: `2500` = `2500`

###### FIREFLIES.emission.mode

> `readonly` **mode**: `"stream"` = `"stream"`

###### FIREFLIES.lifetime

> `readonly` **lifetime**: readonly \[`4000`, `6500`\]

###### FIREFLIES.origin

> `readonly` **origin**: `object`

###### FIREFLIES.origin.x

> `readonly` **x**: readonly \[`0.1`, `0.9`\]

###### FIREFLIES.origin.y

> `readonly` **y**: readonly \[`0.35`, `0.9`\]

###### FIREFLIES.particleCount

> `readonly` **particleCount**: `40` = `40`

###### FIREFLIES.physics

> `readonly` **physics**: `object`

###### FIREFLIES.physics.drag

> `readonly` **drag**: `0.8` = `0.8`

###### FIREFLIES.physics.gravity

> `readonly` **gravity**: `-8` = `-8`

###### FIREFLIES.physics.swirl

> `readonly` **swirl**: `object`

###### FIREFLIES.physics.swirl.frequency

> `readonly` **frequency**: readonly \[`0.2`, `0.5`\]

###### FIREFLIES.physics.swirl.strength

> `readonly` **strength**: readonly \[`30`, `80`\]

###### FIREFLIES.shapes

> `readonly` **shapes**: readonly \[\{ `blendMode`: `"lighter"`; `fadeIn`: `0.25`; `fadeOut`: \{ `easing`: `"easeInOutQuad"`; `start`: `0.6`; \}; `flip`: `false`; `opacity`: readonly \[`0.7`, `1`\]; `rotationSpeed`: `0`; `size`: readonly \[`20`, `34`\]; `src`: `"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAB6klEQVR42s2XzU7CQBSFz4CAWkX8w7hW2cnaFzAuiBvXPp5rN8aF8QVc4w51bURERVD+a9rcIYdhLNhE2yYnt20C57tnZtqpQsij7B4qvi6qazfM/6iwhpbfumGA1C+Mf6omwFidBqJmMGdDFv+eTVn+vSAINUPXWgmjKgNAa2hUNygNNcWcTZNSWXwMDQ0sMBMQKiB2NpoTgCSdJ4wEtGlfqj5nKDcQwGKuDT2lSAwBw7xH6hOQFUJZzDlybZgGkCHp+wygTTukLt3nIRlBqB+6Z3PPcB7AgmhRrnUSoM7bAD4BfInaAjIBMQZgdJ+kyDNkukTSEAygzZskDdOhIRlwCiqg+7SYO2K6QtIQKQHokfk7ybtuCUTXlgID8IxPSYeeybKYrgJYk5pzUNhxsLcL3+HuvoXKA4A3AK8A6lI9iA+Ba1MK/oS0Aej4ufusGK8D2ACwmUfpKIv9A15BDdzeVHF5BeAZQA3Ai4A0jBRGq8IHsCw9Hnsv6pwA5D05KBS3cXJqe4I+4vyshUoZQFVUl1SaxlwYLUkVMP46/px07gFs5VE6Nrs3UrgA8CQANQHQwzAxD2IH8P9DEPkkjNMyjPxBFN2jOPKXUSxex5FvSGKxJYvFpjTybXksPkxi82kWi4/Tv/48/waZ1dSMi+xwdQAAAABJRU5ErkJggg=="`; `type`: `"image"`; `wobble`: `false`; \}\]

###### FIREFLIES.spread

> `readonly` **spread**: `360` = `360`

###### FIREFLIES.startVelocity

> `readonly` **startVelocity**: readonly \[`10`, `40`\]

##### FIREWORKS

> `readonly` **FIREWORKS**: `object`

Fireworks.
Eight round explosions at random spots in the upper half, one every 350 ms.

###### FIREWORKS.emission

> `readonly` **emission**: `object`

###### FIREWORKS.emission.every

> `readonly` **every**: `350` = `350`

###### FIREWORKS.emission.mode

> `readonly` **mode**: `"interval"` = `"interval"`

###### FIREWORKS.emission.times

> `readonly` **times**: `8` = `8`

###### FIREWORKS.lifetime

> `readonly` **lifetime**: readonly \[`1400`, `2000`\]

###### FIREWORKS.origin

> `readonly` **origin**: `object`

###### FIREWORKS.origin.x

> `readonly` **x**: readonly \[`0.15`, `0.85`\]

###### FIREWORKS.origin.y

> `readonly` **y**: readonly \[`0.15`, `0.45`\]

###### FIREWORKS.paper

> `readonly` **paper**: `object`

###### FIREWORKS.paper.fadeOut

> `readonly` **fadeOut**: `object`

###### FIREWORKS.paper.fadeOut.easing

> `readonly` **easing**: `"easeInQuad"` = `"easeInQuad"`

###### FIREWORKS.paper.fadeOut.start

> `readonly` **start**: `0.5` = `0.5`

###### FIREWORKS.paper.flip

> `readonly` **flip**: `false` = `false`

###### FIREWORKS.paper.form

> `readonly` **form**: readonly \[`"circle"`, `"strip"`\]

###### FIREWORKS.paper.scale

> `readonly` **scale**: `0.8` = `0.8`

###### FIREWORKS.paper.shine

> `readonly` **shine**: `0.4` = `0.4`

###### FIREWORKS.particleCount

> `readonly` **particleCount**: `50` = `50`

###### FIREWORKS.physics

> `readonly` **physics**: `object`

###### FIREWORKS.physics.drag

> `readonly` **drag**: `2.4` = `2.4`

###### FIREWORKS.physics.gravity

> `readonly` **gravity**: `400` = `400`

###### FIREWORKS.spread

> `readonly` **spread**: `360` = `360`

###### FIREWORKS.startVelocity

> `readonly` **startVelocity**: readonly \[`500`, `1100`\]

##### FORCE\_FIELD

> `readonly` **FORCE\_FIELD**: `object`

Force Field.
A cool-colored rain falls for five seconds; the pointer pushes the drops away as it moves through them (a
negative `physics.attract` strength).

###### FORCE\_FIELD.angle

> `readonly` **angle**: `270` = `270`

###### FORCE\_FIELD.emission

> `readonly` **emission**: `object`

###### FORCE\_FIELD.emission.duration

> `readonly` **duration**: `5000` = `5000`

###### FORCE\_FIELD.emission.mode

> `readonly` **mode**: `"stream"` = `"stream"`

###### FORCE\_FIELD.lifetime

> `readonly` **lifetime**: readonly \[`5000`, `7000`\]

###### FORCE\_FIELD.origin

> `readonly` **origin**: `object`

###### FORCE\_FIELD.origin.x

> `readonly` **x**: readonly \[`0`, `1`\]

###### FORCE\_FIELD.origin.y

> `readonly` **y**: `-0.03` = `-0.03`

###### FORCE\_FIELD.paper

> `readonly` **paper**: `object`

###### FORCE\_FIELD.paper.colors

> `readonly` **colors**: readonly \[`"#00f0ff"`, `"#8ecae6"`, `"#ffffff"`\]

###### FORCE\_FIELD.paper.scale

> `readonly` **scale**: `0.9` = `0.9`

###### FORCE\_FIELD.paper.width

> `readonly` **width**: readonly \[`4`, `7`\]

###### FORCE\_FIELD.particleCount

> `readonly` **particleCount**: `260` = `260`

###### FORCE\_FIELD.physics

> `readonly` **physics**: `object`

###### FORCE\_FIELD.physics.attract

> `readonly` **attract**: `object`

###### FORCE\_FIELD.physics.attract.falloff

> `readonly` **falloff**: `"linear"` = `"linear"`

###### FORCE\_FIELD.physics.attract.radius

> `readonly` **radius**: `160` = `160`

###### FORCE\_FIELD.physics.attract.strength

> `readonly` **strength**: `-2600` = `-2600`

###### FORCE\_FIELD.physics.attract.target

> `readonly` **target**: `"pointer"` = `"pointer"`

###### FORCE\_FIELD.physics.drag

> `readonly` **drag**: `1.2` = `1.2`

###### FORCE\_FIELD.physics.gravity

> `readonly` **gravity**: `220` = `220`

###### FORCE\_FIELD.spread

> `readonly` **spread**: `20` = `20`

###### FORCE\_FIELD.startVelocity

> `readonly` **startVelocity**: readonly \[`150`, `320`\]

##### GOLDEN

> `readonly` **GOLDEN**: `object`

Golden.
Gold paper with strong glints as the pieces flip (the colors of `KonfetiPalettes.GOLD`).

###### GOLDEN.origin

> `readonly` **origin**: `object`

###### GOLDEN.origin.y

> `readonly` **y**: `0.7` = `0.7`

###### GOLDEN.paper

> `readonly` **paper**: `object`

###### GOLDEN.paper.colors

> `readonly` **colors**: readonly \[`"#ffd700"`, `"#ffcc33"`, `"#f5b700"`, `"#e6be8a"`, `"#fff1b8"`, `"#c9a227"`\]

###### GOLDEN.paper.flip

> `readonly` **flip**: `object`

###### GOLDEN.paper.flip.frequency

> `readonly` **frequency**: readonly \[`0.8`, `1.6`\]

###### GOLDEN.paper.form

> `readonly` **form**: readonly \[`"rect"`, `"strip"`\]

###### GOLDEN.paper.shine

> `readonly` **shine**: `0.9` = `0.9`

###### GOLDEN.particleCount

> `readonly` **particleCount**: `160` = `160`

###### GOLDEN.spread

> `readonly` **spread**: `80` = `80`

###### GOLDEN.startVelocity

> `readonly` **startVelocity**: readonly \[`1200`, `1800`\]

##### HEART\_BURST

> `readonly` **HEART\_BURST**: `object`

Heart Burst.
Pink hearts popping out in every direction and shrinking as they fade.

###### HEART\_BURST.particleCount

> `readonly` **particleCount**: `40` = `40`

###### HEART\_BURST.physics

> `readonly` **physics**: `object`

###### HEART\_BURST.physics.drag

> `readonly` **drag**: `2` = `2`

###### HEART\_BURST.physics.gravity

> `readonly` **gravity**: `200` = `200`

###### HEART\_BURST.shapes

> `readonly` **shapes**: readonly \[\{ `colors`: readonly \[`"#ff4d6d"`, `"#ff758f"`, `"#ff8fa3"`, `"#c9184a"`\]; `flip`: \{ `axis`: `"y"`; \}; `scaleOverLife`: \{ `to`: `0.6`; \}; `size`: readonly \[`14`, `22`\]; `type`: `"heart"`; \}\]

###### HEART\_BURST.spread

> `readonly` **spread**: `360` = `360`

###### HEART\_BURST.startVelocity

> `readonly` **startVelocity**: readonly \[`400`, `900`\]

##### JACKPOT

> `readonly` **JACKPOT**: `object`

Jackpot.
Gold coins pour down for one and a half seconds, spin, bounce on the bottom edge and settle there (shows the
`floor`).

###### JACKPOT.angle

> `readonly` **angle**: `270` = `270`

###### JACKPOT.emission

> `readonly` **emission**: `object`

###### JACKPOT.emission.duration

> `readonly` **duration**: `1500` = `1500`

###### JACKPOT.emission.mode

> `readonly` **mode**: `"stream"` = `"stream"`

###### JACKPOT.lifetime

> `readonly` **lifetime**: readonly \[`4500`, `6000`\]

###### JACKPOT.origin

> `readonly` **origin**: `object`

###### JACKPOT.origin.x

> `readonly` **x**: readonly \[`0.1`, `0.9`\]

###### JACKPOT.origin.y

> `readonly` **y**: `-0.05` = `-0.05`

###### JACKPOT.paper

> `readonly` **paper**: `object`

###### JACKPOT.paper.aspectRatio

> `readonly` **aspectRatio**: `1` = `1`

###### JACKPOT.paper.colors

> `readonly` **colors**: readonly \[`"#ffd700"`, `"#ffcc33"`, `"#f5b700"`, `"#c9a227"`\]

###### JACKPOT.paper.fadeOut

> `readonly` **fadeOut**: `object`

###### JACKPOT.paper.fadeOut.start

> `readonly` **start**: `0.85` = `0.85`

###### JACKPOT.paper.flip

> `readonly` **flip**: `object`

###### JACKPOT.paper.flip.axis

> `readonly` **axis**: `"x"` = `"x"`

###### JACKPOT.paper.flip.frequency

> `readonly` **frequency**: readonly \[`1.5`, `3`\]

###### JACKPOT.paper.form

> `readonly` **form**: `"circle"` = `"circle"`

###### JACKPOT.paper.shine

> `readonly` **shine**: `0.9` = `0.9`

###### JACKPOT.paper.stroke

> `readonly` **stroke**: `object`

###### JACKPOT.paper.stroke.color

> `readonly` **color**: `"#a67c00"` = `"#a67c00"`

###### JACKPOT.paper.stroke.width

> `readonly` **width**: `1.2` = `1.2`

###### JACKPOT.paper.width

> `readonly` **width**: readonly \[`12`, `16`\]

###### JACKPOT.particleCount

> `readonly` **particleCount**: `120` = `120`

###### JACKPOT.physics

> `readonly` **physics**: `object`

###### JACKPOT.physics.drag

> `readonly` **drag**: `0.8` = `0.8`

###### JACKPOT.physics.floor

> `readonly` **floor**: `object`

###### JACKPOT.physics.floor.bounce

> `readonly` **bounce**: `0.45` = `0.45`

###### JACKPOT.physics.floor.friction

> `readonly` **friction**: `0.5` = `0.5`

###### JACKPOT.physics.floor.y

> `readonly` **y**: `1` = `1`

###### JACKPOT.physics.gravity

> `readonly` **gravity**: `1400` = `1400`

###### JACKPOT.spread

> `readonly` **spread**: `25` = `25`

###### JACKPOT.startVelocity

> `readonly` **startVelocity**: readonly \[`150`, `400`\]

##### LEVEL\_UP

> `readonly` **LEVEL\_UP**: readonly \[\{ `formation`: \{ `assemble`: `800`; `font`: `"900 110px sans-serif"`; `hold`: `1000`; `text`: `"LEVEL UP!"`; \}; `origin`: \{ `x`: `0.5`; `y`: `0.4`; \}; `paper`: \{ `colors`: readonly \[`"#39ff14"`, `"#00f0ff"`, `"#fff01f"`, `"#ff6ec7"`\]; \}; `shapes`: readonly \[\{ `type`: `"paper"`; `weight`: `3`; \}, \{ `colors`: readonly \[`"#fff01f"`, `"#ffe400"`, `"#fdffb8"`\]; `size`: readonly \[`9`, `13`\]; `type`: `"star"`; \}\]; \}, \{ `lifetime`: readonly \[`900`, `1300`\]; `origin`: \{ `x`: readonly \[`0.15`, `0.85`\]; `y`: `1.02`; \}; `particleCount`: `24`; `physics`: \{ `drag`: `1`; `gravity`: `900`; \}; `shapes`: readonly \[\{ `colors`: readonly \[`"#fff01f"`, `"#ffe400"`, `"#fdffb8"`\]; `size`: readonly \[`9`, `13`\]; `trail`: \{ `length`: `20`; `opacity`: `0.7`; `width`: readonly \[`2`, `3`\]; \}; `type`: `"star"`; \}\]; `spread`: `30`; `startVelocity`: readonly \[`1500`, `2100`\]; \}, \{ `delay`: `1800`; `lifetime`: readonly \[`1400`, `2000`\]; `origin`: \{ `x`: `0.5`; `y`: `0.4`; \}; `particleCount`: `70`; `physics`: \{ `drag`: `2.5`; `gravity`: `500`; \}; `shapes`: readonly \[\{ `colors`: readonly \[`"#fff01f"`, `"#ffe400"`, `"#fdffb8"`\]; `shine`: `0.6`; `size`: readonly \[`10`, `16`\]; `type`: `"star"`; \}\]; `spread`: `360`; `startVelocity`: readonly \[`600`, `1200`\]; \}\]

Level Up.
"LEVEL UP!" assembles while stars with trails shoot up from below, and a star burst follows the moment the
letters break apart (a list choreographed with `delay`).

##### LOGO\_REVEAL

> `readonly` **LOGO\_REVEAL**: `object`

Logo Reveal.
A star badge appears made of confetti in its own colors, then bursts apart (shows an image `formation`;
the badge is a small PNG data URL, so it also works in worker instances).

###### LOGO\_REVEAL.formation

> `readonly` **formation**: `object`

###### LOGO\_REVEAL.formation.hold

> `readonly` **hold**: `1500` = `1500`

###### LOGO\_REVEAL.formation.image

> `readonly` **image**: `"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAACO0lEQVR42s1Xr08DMRS+P+Uk7mYQJIgFFGJhCgxiFhQCdwEzQ8gEggSzZIaQIBaCQCCWEwuKQKZwMDUE5hJMxwYr+W7tpdfrde8GC9fkJffjvX6v78fX1nHmGL7HXN9jZU1cZ5HD91jV91jL91joe4xnSCh0qn8JXPM91pcgjY0hbx+OeOd8nBB8wz/FGdjUfgOMMAeYrL465LcnYx4OJlwdeDd9gy5shCNB7vT4HivJUF/sjzj7mE7++vBtWmkiMtDBgA1sldSUcoM/3XzFwGdbn9yS+4RAVzqCOchOiLAnwBFOKrAusDU44docCFRwhNQGUF95j8Smgzk0JwJbtUd5o668vXcVCTUSSk3UTA70UbkoHuSPEuK3681IKLqYE3OL7uibSCb2lFJwjfUXzh+XIsEzpTC1yFZVB8BeUQ9TV985Oo0dwDM1CsAQ7y3VgRB9TCk8KeHdWuwAnik2siAFj4Rq6+k/p2Gr9KLV6XJ/XI/BpeCbSRdzqGSlLdJ1xE4W8TlGqoIPmikwqsBWnw8DWOK9nHBAyU9CmttdzrrLZGDowsaYusEkvwOSdNBys8ChYyMnqwOmFKQq+XInExz/ZtmbUpBZhFnkY1u9lTtMRZinDVXyyRIbKRnbMA8RgfdVMNlq6jfb3mAjIhIVPzd341Cr/Y1nmRro5KZi6maE9rLRLv5BJ/dmRNmOkVt11ZmbTqWXqgPSdjzPgSQP/888kBTiSPbvh9JCHMsLcTEpxNWsMJfTRV/PfwCRz6O9nmJS6gAAAABJRU5ErkJggg=="` = `"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAACO0lEQVR42s1Xr08DMRS+P+Uk7mYQJIgFFGJhCgxiFhQCdwEzQ8gEggSzZIaQIBaCQCCWEwuKQKZwMDUE5hJMxwYr+W7tpdfrde8GC9fkJffjvX6v78fX1nHmGL7HXN9jZU1cZ5HD91jV91jL91joe4xnSCh0qn8JXPM91pcgjY0hbx+OeOd8nBB8wz/FGdjUfgOMMAeYrL465LcnYx4OJlwdeDd9gy5shCNB7vT4HivJUF/sjzj7mE7++vBtWmkiMtDBgA1sldSUcoM/3XzFwGdbn9yS+4RAVzqCOchOiLAnwBFOKrAusDU44docCFRwhNQGUF95j8Smgzk0JwJbtUd5o668vXcVCTUSSk3UTA70UbkoHuSPEuK3681IKLqYE3OL7uibSCb2lFJwjfUXzh+XIsEzpTC1yFZVB8BeUQ9TV985Oo0dwDM1CsAQ7y3VgRB9TCk8KeHdWuwAnik2siAFj4Rq6+k/p2Gr9KLV6XJ/XI/BpeCbSRdzqGSlLdJ1xE4W8TlGqoIPmikwqsBWnw8DWOK9nHBAyU9CmttdzrrLZGDowsaYusEkvwOSdNBys8ChYyMnqwOmFKQq+XInExz/ZtmbUpBZhFnkY1u9lTtMRZinDVXyyRIbKRnbMA8RgfdVMNlq6jfb3mAjIhIVPzd341Cr/Y1nmRro5KZi6maE9rLRLv5BJ/dmRNmOkVt11ZmbTqWXqgPSdjzPgSQP/888kBTiSPbvh9JCHMsLcTEpxNWsMJfTRV/PfwCRz6O9nmJS6gAAAABJRU5ErkJggg=="`

###### LOGO\_REVEAL.formation.mode

> `readonly` **mode**: `"appear"` = `"appear"`

###### LOGO\_REVEAL.formation.spacing

> `readonly` **spacing**: `7` = `7`

###### LOGO\_REVEAL.formation.width

> `readonly` **width**: `260` = `260`

###### LOGO\_REVEAL.origin

> `readonly` **origin**: `object`

###### LOGO\_REVEAL.origin.x

> `readonly` **x**: `0.5` = `0.5`

###### LOGO\_REVEAL.origin.y

> `readonly` **y**: `0.45` = `0.45`

###### LOGO\_REVEAL.paper

> `readonly` **paper**: `object`

###### LOGO\_REVEAL.paper.scale

> `readonly` **scale**: `0.7` = `0.7`

##### MAGNET

> `readonly` **MAGNET**: `object`

Magnet.
A slow, floating cloud that follows the pointer while it moves over the page (shows `physics.attract`).

###### MAGNET.lifetime

> `readonly` **lifetime**: readonly \[`6000`, `8000`\]

###### MAGNET.origin

> `readonly` **origin**: `object`

###### MAGNET.origin.x

> `readonly` **x**: `0.5` = `0.5`

###### MAGNET.origin.y

> `readonly` **y**: `0.5` = `0.5`

###### MAGNET.paper

> `readonly` **paper**: `object`

###### MAGNET.paper.fadeOut

> `readonly` **fadeOut**: `object`

###### MAGNET.paper.fadeOut.start

> `readonly` **start**: `0.8` = `0.8`

###### MAGNET.paper.scale

> `readonly` **scale**: `0.8` = `0.8`

###### MAGNET.particleCount

> `readonly` **particleCount**: `150` = `150`

###### MAGNET.physics

> `readonly` **physics**: `object`

###### MAGNET.physics.attract

> `readonly` **attract**: `object`

###### MAGNET.physics.attract.falloff

> `readonly` **falloff**: `"linear"` = `"linear"`

###### MAGNET.physics.attract.radius

> `readonly` **radius**: `500` = `500`

###### MAGNET.physics.attract.strength

> `readonly` **strength**: `1600` = `1600`

###### MAGNET.physics.attract.target

> `readonly` **target**: `"pointer"` = `"pointer"`

###### MAGNET.physics.drag

> `readonly` **drag**: `1.6` = `1.6`

###### MAGNET.physics.gravity

> `readonly` **gravity**: `60` = `60`

###### MAGNET.physics.swirl

> `readonly` **swirl**: `object`

###### MAGNET.physics.swirl.frequency

> `readonly` **frequency**: readonly \[`0.3`, `0.8`\]

###### MAGNET.physics.swirl.strength

> `readonly` **strength**: readonly \[`120`, `280`\]

###### MAGNET.spread

> `readonly` **spread**: `360` = `360`

###### MAGNET.startVelocity

> `readonly` **startVelocity**: readonly \[`200`, `700`\]

##### REALISTIC

> `readonly` **REALISTIC**: readonly \[\{ `origin`: \{ `y`: `0.7`; \}; `particleCount`: `50`; `physics`: \{ `drag`: `3.5`; \}; `spread`: `26`; `startVelocity`: readonly \[`1700`, `2300`\]; \}, \{ `origin`: \{ `y`: `0.7`; \}; `particleCount`: `40`; `physics`: \{ `drag`: `3.5`; \}; `spread`: `60`; `startVelocity`: readonly \[`1360`, `1840`\]; \}, \{ `origin`: \{ `y`: `0.7`; \}; `paper`: \{ `scale`: `0.8`; \}; `particleCount`: `70`; `physics`: \{ `drag`: `5.5`; \}; `spread`: `100`; `startVelocity`: readonly \[`1360`, `1840`\]; \}, \{ `origin`: \{ `y`: `0.7`; \}; `paper`: \{ `scale`: `1.2`; \}; `particleCount`: `20`; `physics`: \{ `drag`: `5`; \}; `spread`: `120`; `startVelocity`: readonly \[`765`, `1035`\]; \}, \{ `origin`: \{ `y`: `0.7`; \}; `particleCount`: `20`; `physics`: \{ `drag`: `3.5`; \}; `spread`: `120`; `startVelocity`: readonly \[`1360`, `1840`\]; \}\]

Realistic.
Five overlapping bursts with different spreads, speeds and sizes (200 particles in total) for a natural,
layered pop.

##### SCHOOL\_PRIDE

> `readonly` **SCHOOL\_PRIDE**: readonly \[\{ `angle`: `60`; `emission`: \{ `duration`: `3000`; `mode`: `"stream"`; \}; `origin`: \{ `x`: `0`; `y`: `0.65`; \}; `paper`: \{ `colors`: readonly \[`"#bb0000"`, `"#ffffff"`\]; \}; `particleCount`: `160`; `spread`: `55`; `startVelocity`: readonly \[`1300`, `1900`\]; \}, \{ `angle`: `120`; `emission`: \{ `duration`: `3000`; `mode`: `"stream"`; \}; `origin`: \{ `x`: `1`; `y`: `0.65`; \}; `paper`: \{ `colors`: readonly \[`"#bb0000"`, `"#ffffff"`\]; \}; `particleCount`: `160`; `spread`: `55`; `startVelocity`: readonly \[`1300`, `1900`\]; \}\]

School Pride.
Red and white streams from both sides for three seconds.

##### SHOOTING\_STARS

> `readonly` **SHOOTING\_STARS**: `object`

Shooting Stars.
Pale golden stars streaking down across the upper sky with long, fading trails, in six quick volleys
(shows the `trail` style option).

###### SHOOTING\_STARS.angle

> `readonly` **angle**: readonly \[`-35`, `-20`\]

###### SHOOTING\_STARS.emission

> `readonly` **emission**: `object`

###### SHOOTING\_STARS.emission.every

> `readonly` **every**: `220` = `220`

###### SHOOTING\_STARS.emission.mode

> `readonly` **mode**: `"interval"` = `"interval"`

###### SHOOTING\_STARS.emission.times

> `readonly` **times**: `6` = `6`

###### SHOOTING\_STARS.lifetime

> `readonly` **lifetime**: readonly \[`900`, `1300`\]

###### SHOOTING\_STARS.origin

> `readonly` **origin**: `object`

###### SHOOTING\_STARS.origin.x

> `readonly` **x**: readonly \[`0.05`, `0.6`\]

###### SHOOTING\_STARS.origin.y

> `readonly` **y**: readonly \[`0.05`, `0.3`\]

###### SHOOTING\_STARS.particleCount

> `readonly` **particleCount**: `5` = `5`

###### SHOOTING\_STARS.physics

> `readonly` **physics**: `object`

###### SHOOTING\_STARS.physics.drag

> `readonly` **drag**: `0.6` = `0.6`

###### SHOOTING\_STARS.physics.gravity

> `readonly` **gravity**: `120` = `120`

###### SHOOTING\_STARS.shapes

> `readonly` **shapes**: readonly \[\{ `colors`: readonly \[`"#fffbe6"`, `"#ffe38a"`, `"#ffd23f"`\]; `shine`: `0.6`; `size`: readonly \[`8`, `12`\]; `trail`: \{ `length`: `24`; `opacity`: `0.75`; `width`: readonly \[`2`, `3`\]; \}; `type`: `"star"`; \}\]

###### SHOOTING\_STARS.spread

> `readonly` **spread**: `8` = `8`

###### SHOOTING\_STARS.startVelocity

> `readonly` **startVelocity**: readonly \[`900`, `1400`\]

##### SIDE\_SHOTS

> `readonly` **SIDE\_SHOTS**: readonly \[\{ `angle`: `60`; `origin`: \{ `x`: `0`; `y`: `0.75`; \}; `particleCount`: `70`; `spread`: `55`; `startVelocity`: readonly \[`1400`, `2200`\]; \}, \{ `angle`: `120`; `origin`: \{ `x`: `1`; `y`: `0.75`; \}; `particleCount`: `70`; `spread`: `55`; `startVelocity`: readonly \[`1400`, `2200`\]; \}\]

Side Shots.
Two bursts at once, from the left and right edges, aimed towards the center.

##### SNOW

> `readonly` **SNOW**: `object`

Snow.
Soft round flakes and six-armed snow crystals drifting down from the top edge for six seconds.

###### SNOW.angle

> `readonly` **angle**: `270` = `270`

###### SNOW.emission

> `readonly` **emission**: `object`

###### SNOW.emission.duration

> `readonly` **duration**: `6000` = `6000`

###### SNOW.emission.mode

> `readonly` **mode**: `"stream"` = `"stream"`

###### SNOW.lifetime

> `readonly` **lifetime**: readonly \[`6000`, `9000`\]

###### SNOW.origin

> `readonly` **origin**: `object`

###### SNOW.origin.x

> `readonly` **x**: readonly \[`0`, `1`\]

###### SNOW.origin.y

> `readonly` **y**: `-0.03` = `-0.03`

###### SNOW.paper

> `readonly` **paper**: `object`

###### SNOW.paper.aspectRatio

> `readonly` **aspectRatio**: `1` = `1`

###### SNOW.paper.colors

> `readonly` **colors**: readonly \[`"#ffffff"`, `"#e8f4ff"`\]

###### SNOW.paper.fadeIn

> `readonly` **fadeIn**: `0.05` = `0.05`

###### SNOW.paper.flip

> `readonly` **flip**: `false` = `false`

###### SNOW.paper.form

> `readonly` **form**: `"circle"` = `"circle"`

###### SNOW.paper.opacity

> `readonly` **opacity**: readonly \[`0.6`, `1`\]

###### SNOW.paper.rotationSpeed

> `readonly` **rotationSpeed**: `0` = `0`

###### SNOW.paper.width

> `readonly` **width**: readonly \[`3`, `7`\]

###### SNOW.paper.wobble

> `readonly` **wobble**: `object`

###### SNOW.paper.wobble.amplitude

> `readonly` **amplitude**: readonly \[`4`, `12`\]

###### SNOW.paper.wobble.frequency

> `readonly` **frequency**: readonly \[`0.2`, `0.5`\]

###### SNOW.particleCount

> `readonly` **particleCount**: `180` = `180`

###### SNOW.physics

> `readonly` **physics**: `object`

###### SNOW.physics.drag

> `readonly` **drag**: `0.4` = `0.4`

###### SNOW.physics.gravity

> `readonly` **gravity**: `30` = `30`

###### SNOW.physics.swirl

> `readonly` **swirl**: `object`

###### SNOW.physics.swirl.frequency

> `readonly` **frequency**: readonly \[`0.1`, `0.3`\]

###### SNOW.physics.swirl.strength

> `readonly` **strength**: readonly \[`10`, `30`\]

###### SNOW.physics.wind

> `readonly` **wind**: readonly \[`-10`, `10`\]

###### SNOW.shapes

> `readonly` **shapes**: readonly \[\{ `type`: `"paper"`; `weight`: `3`; \}, \{ `path`: `"M12 1.5L12 22.5M21.1 6.8L2.9 17.3M2.9 6.8L21.1 17.3M9.6 3.4L12 5.8L14.4 3.4M3.3 9.8L6.6 8.9L5.7 5.6M5.7 18.4L6.6 15.1L3.3 14.2M14.4 20.6L12 18.2L9.6 20.6M20.7 14.2L17.4 15.1L18.3 18.4M18.3 5.6L17.4 8.9L20.7 9.8"`; `rotationSpeed`: readonly \[`-40`, `40`\]; `size`: readonly \[`10`, `17`\]; `stroke`: \{ `color`: `"#ffffff"`; `width`: readonly \[`1`, `1.5`\]; \}; `type`: `"path"`; `weight`: `1`; \}\]

###### SNOW.spread

> `readonly` **spread**: `30` = `30`

###### SNOW.startVelocity

> `readonly` **startVelocity**: readonly \[`20`, `80`\]

##### SPARKLER

> `readonly` **SPARKLER**: `object`

Sparkler.
Hot, glowing sparks with short trails spray from the center for one and a half seconds (additive `lighter`
blending: brightest on dark backgrounds).

###### SPARKLER.emission

> `readonly` **emission**: `object`

###### SPARKLER.emission.duration

> `readonly` **duration**: `1500` = `1500`

###### SPARKLER.emission.mode

> `readonly` **mode**: `"stream"` = `"stream"`

###### SPARKLER.lifetime

> `readonly` **lifetime**: readonly \[`500`, `900`\]

###### SPARKLER.origin

> `readonly` **origin**: `object`

###### SPARKLER.origin.x

> `readonly` **x**: `0.5` = `0.5`

###### SPARKLER.origin.y

> `readonly` **y**: `0.5` = `0.5`

###### SPARKLER.paper

> `readonly` **paper**: `object`

###### SPARKLER.paper.aspectRatio

> `readonly` **aspectRatio**: `1` = `1`

###### SPARKLER.paper.blendMode

> `readonly` **blendMode**: `"lighter"` = `"lighter"`

###### SPARKLER.paper.colors

> `readonly` **colors**: readonly \[`"#fff6d5"`, `"#ffd98a"`, `"#ffb347"`\]

###### SPARKLER.paper.fadeOut

> `readonly` **fadeOut**: `object`

###### SPARKLER.paper.fadeOut.easing

> `readonly` **easing**: `"easeInQuad"` = `"easeInQuad"`

###### SPARKLER.paper.fadeOut.start

> `readonly` **start**: `0.3` = `0.3`

###### SPARKLER.paper.flip

> `readonly` **flip**: `false` = `false`

###### SPARKLER.paper.form

> `readonly` **form**: `"circle"` = `"circle"`

###### SPARKLER.paper.trail

> `readonly` **trail**: `object`

###### SPARKLER.paper.trail.length

> `readonly` **length**: `10` = `10`

###### SPARKLER.paper.trail.opacity

> `readonly` **opacity**: `0.8` = `0.8`

###### SPARKLER.paper.trail.width

> `readonly` **width**: readonly \[`1.5`, `2.5`\]

###### SPARKLER.paper.width

> `readonly` **width**: readonly \[`2`, `3.5`\]

###### SPARKLER.paper.wobble

> `readonly` **wobble**: `false` = `false`

###### SPARKLER.particleCount

> `readonly` **particleCount**: `220` = `220`

###### SPARKLER.physics

> `readonly` **physics**: `object`

###### SPARKLER.physics.drag

> `readonly` **drag**: `2` = `2`

###### SPARKLER.physics.gravity

> `readonly` **gravity**: `500` = `500`

###### SPARKLER.spread

> `readonly` **spread**: `360` = `360`

###### SPARKLER.startVelocity

> `readonly` **startVelocity**: readonly \[`400`, `1100`\]

##### STARS

> `readonly` **STARS**: `object`

Stars.
A golden, shiny star burst in every direction from the center.

###### STARS.lifetime

> `readonly` **lifetime**: readonly \[`1800`, `2600`\]

###### STARS.origin

> `readonly` **origin**: `object`

###### STARS.origin.x

> `readonly` **x**: `0.5` = `0.5`

###### STARS.origin.y

> `readonly` **y**: `0.45` = `0.45`

###### STARS.particleCount

> `readonly` **particleCount**: `60` = `60`

###### STARS.physics

> `readonly` **physics**: `object`

###### STARS.physics.drag

> `readonly` **drag**: `2.5` = `2.5`

###### STARS.physics.gravity

> `readonly` **gravity**: `250` = `250`

###### STARS.shapes

> `readonly` **shapes**: readonly \[\{ `colors`: readonly \[`"#ffe400"`, `"#ffbd00"`, `"#e89400"`, `"#ffca6c"`, `"#fdffb8"`\]; `shine`: `0.6`; `size`: readonly \[`12`, `20`\]; `type`: `"star"`; \}\]

###### STARS.spread

> `readonly` **spread**: `360` = `360`

###### STARS.startVelocity

> `readonly` **startVelocity**: readonly \[`500`, `1100`\]

##### SUCCESS

> `readonly` **SUCCESS**: `object`

Success.
A green check mark appears made of confetti, then bursts apart (for "saved", "sent", "done" moments).

###### SUCCESS.formation

> `readonly` **formation**: `object`

###### SUCCESS.formation.font

> `readonly` **font**: `"900 220px sans-serif"` = `"900 220px sans-serif"`

###### SUCCESS.formation.hold

> `readonly` **hold**: `900` = `900`

###### SUCCESS.formation.mode

> `readonly` **mode**: `"appear"` = `"appear"`

###### SUCCESS.formation.spacing

> `readonly` **spacing**: `7` = `7`

###### SUCCESS.formation.text

> `readonly` **text**: `"✔"` = `"✔"`

###### SUCCESS.origin

> `readonly` **origin**: `object`

###### SUCCESS.origin.x

> `readonly` **x**: `0.5` = `0.5`

###### SUCCESS.origin.y

> `readonly` **y**: `0.45` = `0.45`

###### SUCCESS.paper

> `readonly` **paper**: `object`

###### SUCCESS.paper.colors

> `readonly` **colors**: readonly \[`"#2dc653"`, `"#25a244"`, `"#6ede8a"`, `"#b7efc5"`\]

###### SUCCESS.paper.scale

> `readonly` **scale**: `0.8` = `0.8`

#### Example

```ts
import { Konfeti, KonfetiPresets, extendPreset } from "konfeti";

Konfeti.fire(KonfetiPresets.FIREWORKS);
Konfeti.fire(extendPreset(KonfetiPresets.SNOW, { emission: { mode: "stream", duration: 10000 } }));
Konfeti.fire(extendPreset(KonfetiPresets.STARS, { origin: document.querySelector("#badge")! }));
```

#### Remarks

Only in the full `konfeti` entry: presets use several shapes, which `konfeti/lite` leaves out.

***

### paperShape

> `const` **paperShape**: [`ShapeHandler`](#shapehandler)\<[`PaperShapeOptions`](#papershapeoptions)\>

Default Paper Shape Handler.
Always registered — it is the shape used when `shapes` is omitted.

***

### pathShape

> `const` **pathShape**: [`ShapeHandler`](#shapehandler)\<[`PathShapeOptions`](#pathshapeoptions)\>

Custom SVG Path Shape Handler.

***

### polygonShape

> `const` **polygonShape**: [`ShapeHandler`](#shapehandler)\<[`PolygonShapeOptions`](#polygonshapeoptions)\>

Regular Polygon Shape Handler.

***

### ribbonShape

> `const` **ribbonShape**: [`ShapeHandler`](#shapehandler)\<[`RibbonShapeOptions`](#ribbonshapeoptions)\>

Curly Ribbon Shape Handler.

***

### spritesheetShape

> `const` **spritesheetShape**: [`ShapeHandler`](#shapehandler)\<[`SpriteSheetShapeOptions`](#spritesheetshapeoptions)\>

Animated Spritesheet Shape Handler.

***

### starShape

> `const` **starShape**: [`ShapeHandler`](#shapehandler)\<[`StarShapeOptions`](#starshapeoptions)\>

Star Shape Handler.

***

### textShape

> `const` **textShape**: [`ShapeHandler`](#shapehandler)\<[`TextShapeOptions`](#textshapeoptions)\>

Text Shape Handler (one raster per text × palette color).

***

### triangleShape

> `const` **triangleShape**: [`ShapeHandler`](#shapehandler)\<[`TriangleShapeOptions`](#triangleshapeoptions)\>

Triangle Shape Handler.

***

### VERSION

> `const` **VERSION**: `"0.6.0"` = `"0.6.0"`

Konfeti Library Version.
Replaced with the real package version at release time.

## Functions

### definePhysics()

> **definePhysics**\<`K`\>(`name`, `definition`): `void`

Register Custom Physics Module.
Declare its options on [PhysicsRegistry](#physicsregistry) first; enable it per burst with `physics: { name: … }`.
Registering the same name again replaces the definition.

#### Type Parameters

##### K

`K` *extends* `never`

#### Parameters

##### name

`K`

Module Name (not a built-in physics key)

##### definition

[`PhysicsDefinition`](#physicsdefinition)\<[`PhysicsRegistry`](#physicsregistry)\[`K`\] & `object`\>

Module Definition

#### Returns

`void`

#### Throws

TypeError for built-in keys

#### Example

```ts
declare module "konfeti" {
  interface PhysicsRegistry {
    magnet: { x: number; y: number; strength: number };
  }
}

definePhysics("magnet", {
  defaults: { x: 0.5, y: 0.5, strength: 600 },
  apply: (p, dt, world, { x, y, strength }) => {
    p.vx += (x * world.width - p.x) * strength * dt * 0.001;
    p.vy += (y * world.height - p.y) * strength * dt * 0.001;
  },
});

Konfeti.fire({ physics: { magnet: { strength: 900 } } });
```

***

### defineShape()

> **defineShape**\<`K`\>(`name`, `definition`): `void`

Register Custom Shape.
Declare its options on [ShapeRegistry](#shaperegistry) first; the name then becomes a typed `shapes[].type`.
Registering the same name again replaces the definition.

#### Type Parameters

##### K

`K` *extends* `never`

#### Parameters

##### name

`K`

Shape Type Name (not a built-in name)

##### definition

[`ShapeDefinition`](#shapedefinition)\<[`ShapeRegistry`](#shaperegistry)\[`K`\] & `object`\>

Path- or Draw-Based Definition

#### Returns

`void`

#### Throws

TypeError for built-in names

#### Example

```ts
declare module "konfeti" {
  interface ShapeRegistry {
    diamond: { sharpness?: number };
  }
}

defineShape("diamond", {
  path: ({ sharpness = 0.5 }) => `M12 0L${24 - sharpness * 12} 12L12 24L${sharpness * 12} 12Z`,
});

Konfeti.fire({ shapes: [{ type: "diamond", sharpness: 0.8 }] });
```

***

### disableBanner()

> **disableBanner**(): `void`

Turn Off the Console Banner.
konfeti logs its version and renderer once per page, when the first instance is created (the shared
`Konfeti` on its first `fire()`, or `KonfetiFactory.create()` / `createWorker()`). Call this before that to
keep the console silent.

#### Returns

`void`

#### Example

```ts
import { Konfeti, disableBanner } from "konfeti";

disableBanner();
Konfeti.fire(); // no console output
```

***

### enableFormations()

> **enableFormations**(): `void`

Enable Formations (text and images made of particles).
The full `konfeti` entry and `konfeti/worker` call it for you. With `konfeti/lite`, call it once before
firing a `formation`, so lite bundles that never form shapes stay small. Calling it again is harmless.

#### Returns

`void`

#### Example

```ts
import { Konfeti, enableFormations } from "konfeti/lite";

enableFormations();
Konfeti.fire({ formation: { text: "HELLO" } });
```

***

### extendPreset()

> **extendPreset**(`preset`, `overrides`): [`FireInput`](#fireinput)

Combine a Preset with Your Own Settings.
Returns new options with `overrides` merged into every burst of the preset (a preset such as
`SIDE_SHOTS` has several). Top-level keys are replaced; `paper` and `physics` merge key by key, so you
can change one paper setting without losing the preset's others. The preset itself is never modified.

#### Parameters

##### preset

[`FireInput`](#fireinput)

Preset (or any fire input) to Start from

##### overrides

[`FireOptions`](#fireoptions)

Settings that Win over the Preset

#### Returns

[`FireInput`](#fireinput)

Fire Input to Pass to `fire()`

#### Example

```ts
Konfeti.fire(extendPreset(KonfetiPresets.SNOW, { emission: { mode: "stream", duration: 10000 } }));
Konfeti.fire(extendPreset(KonfetiPresets.SIDE_SHOTS, { paper: { colors: ["gold", "white"] } }));
```

***

### framesFromAtlas()

> **framesFromAtlas**(`atlas`, `prefix?`): [`FrameRect`](#framerect)[]

Turn a Sprite Atlas JSON into Spritesheet Frames.
Reads the frame list that TexturePacker, Aseprite, Free Texture Packer or Phaser export next to a packed sheet, in
the order the atlas lists them, and returns the rectangles a `spritesheet` shape's `frames` takes. A name prefix
picks one animation out of an atlas that holds several.

#### Parameters

##### atlas

[`SpriteAtlas`](#spriteatlas)

Atlas JSON ("JSON Hash" or "JSON Array" layout)

##### prefix?

`string` = `""`

Only Frames Whose Name Starts with This (default: every frame)

#### Returns

[`FrameRect`](#framerect)[]

Frame Rectangles in Atlas Order

#### Throws

TypeError for a malformed atlas, a rotated frame, or no frame matching the prefix

#### Example

```ts
import atlas from "./coins.json";

Konfeti.fire({
  shapes: [{ type: "spritesheet", src: "/coins.png", frames: framesFromAtlas(atlas, "coin_spin") }],
});
```

#### Remarks

Trimmed frames of different sizes are each stretched to the particle size; export animations without
trimming (or with "keep size") so they do not wobble.

***

### loadImage()

> **loadImage**(`url`): `Promise`\<`HTMLImageElement`\>

Preload Image by URL.
Uses the same cache as `image` / `spritesheet` shapes, so firing afterwards draws immediately.

#### Parameters

##### url

`string`

Image URL

#### Returns

`Promise`\<`HTMLImageElement`\>

Promise Resolving with the Loaded Image

#### Example

```ts
await loadImage("/coin.png");
Konfeti.fire({ shapes: [{ type: "image", src: "/coin.png" }] });
```

***

### registerShapes()

> **registerShapes**(...`handlers`): `void`

Register Built-in Shape Handlers (for `konfeti/lite`).
The full `konfeti` entry already registers every shape; with `konfeti/lite` only paper is available until
you register the others you use, so unused shapes stay out of your bundle.

#### Parameters

##### handlers

...readonly [`AnyShapeHandler`](#anyshapehandler)[]

Shape Handlers (`starShape`, `emojiShape`, …)

#### Returns

`void`

#### Example

```ts
import { Konfeti, registerShapes, starShape, emojiShape } from "konfeti/lite";

registerShapes(starShape, emojiShape);
Konfeti.fire({ shapes: [{ type: "star" }, { type: "emoji", emoji: "🎉" }] });
```

---

# API reference: konfeti/worker

Render in a Web Worker: `import { createWorker } from "konfeti/worker"`.
Kept out of the main entries, so their bundles carry no worker code.

## Classes

### WorkerKonfetiInstance

Konfeti Instance that Simulates and Draws in a Web Worker.
The canvas is handed to the worker as an `OffscreenCanvas`, so confetti stays smooth while the page is busy.
Without `OffscreenCanvas` support it transparently falls back to the main thread (`isWorker()` is `false`).
Created by `createWorker()`.

#### Constructors

##### Constructor

> **new WorkerKonfetiInstance**(`canvas?`, `options?`, `connect?`): [`WorkerKonfetiInstance`](#workerkonfetiinstance)

Create Worker Instance.

###### Parameters

###### canvas?

`HTMLCanvasElement` \| `null`

Target Canvas (`null` creates a fullscreen overlay)

###### options?

[`WorkerCreateOptions`](#workercreateoptions) = `{}`

Worker Instance Options

###### connect?

`WorkerConnector` = `...`

Worker Connector (defaults to the bundled worker script)

###### Returns

[`WorkerKonfetiInstance`](#workerkonfetiinstance)

#### Methods

##### destroy()

> **destroy**(): `void`

Destroy Instance.
Stops the worker, removes listeners and the overlay canvas.

###### Returns

`void`

##### emit()

> **emit**(`options`): [`KonfetiEmitter`](#konfetiemitter)

Start a Continuous Emitter.
Streams particles at `rate` per second until `stop()`. What it follows is measured on the main thread and
sent to the worker.

###### Parameters

###### options

[`WorkerEmitOptions`](#workeremitoptions)

Worker-Safe Emitter Options

###### Returns

[`KonfetiEmitter`](#konfetiemitter)

Emitter Handle

###### Throws

Error when destroyed, TypeError for an invalid `rate` or options that cannot be sent to a worker

###### Example

```ts
const stage = createWorker(canvas);
const trail = stage.emit({ rate: 80, follow: "pointer", spread: 360 });
trail.stop();
```

##### fire()

> **fire**(`input?`): [`KonfetiHandle`](#konfetihandle)

Fire Burst (or Several Bursts at Once).

###### Parameters

###### input?

[`WorkerFireInput`](#workerfireinput) = `{}`

Worker-Safe Burst Options, or an Array of Them

###### Returns

[`KonfetiHandle`](#konfetihandle)

Awaitable Burst Handle (rejects if the worker reports invalid options)

###### Throws

Error when destroyed, TypeError when the options cannot be sent to the worker

###### Example

```ts
const stage = createWorker(canvas);
await stage.fire({ particleCount: 300, spread: 360 });
```

##### getCanvas()

> **getCanvas**(): `HTMLCanvasElement`

Return Canvas Element.

###### Returns

`HTMLCanvasElement`

Canvas Element

##### getParticleCount()

> **getParticleCount**(): `number`

Return Live Particle Count.

###### Returns

`number`

Particle Count (worker mode: updated a few times per second)

##### getQualityLevel()

> **getQualityLevel**(): `number`

Return the Adaptive Quality Level.
Always `0` without the `adaptiveQuality` option.

###### Returns

`number`

Level: `0` full quality, `1` CSS resolution, `2` no shadows / shine / trails, `3` fewer particles
  (worker mode: updated a few times per second)

##### getStats()

> **getStats**(): [`WorkerStats`](#workerstats)

Return Counters.
The worker-mode replacement for hooks (which cannot run in a worker): live, spawned and died particles
and finished bursts. Works the same in main-thread fallback mode.

###### Returns

[`WorkerStats`](#workerstats)

Counters (worker mode: updated a few times per second)

###### Example

```ts
const stage = createWorker(canvas);
await stage.fire({ particleCount: 200 });
stage.getStats(); // { live: 0, spawned: 200, died: 200, completed: 1 }
```

##### isDestroyed()

> **isDestroyed**(): `boolean`

Return Destroyed State.

###### Returns

`boolean`

Destroyed State

##### isPaused()

> **isPaused**(): `boolean`

Check Whether pause() Is in Effect.

###### Returns

`boolean`

Paused Flag

##### isSupported()

> `static` **isSupported**(`canvas`): `boolean`

Check Browser Support for Worker Rendering.

###### Parameters

###### canvas

`HTMLCanvasElement`

Target Canvas

###### Returns

`boolean`

Supported Flag

##### isWorker()

> **isWorker**(): `boolean`

Return Worker Mode State.

###### Returns

`boolean`

`true` when drawing happens in a worker, `false` for the main-thread fallback

##### onClick()

> **onClick**(`target`, `options?`, `settings?`): () => `void`

Fire on Every Click.
Bursts start at the click position unless the options set their own `origin`.

###### Parameters

###### target

`Element` \| `Window`

Element (or `window`) to Listen On

###### options?

[`WorkerFireInput`](#workerfireinput) \| ((`event`) => [`WorkerFireInput`](#workerfireinput))

Worker-Safe Burst Options, or a Function Building Them from the Click Event

###### settings?

[`ClickOptions`](#clickoptions) = `{}`

Trigger Event and Burst Callback

###### Returns

Unsubscribe Function

() => `void`

##### pause()

> **pause**(): `void`

Pause Everything.
Freezes every running burst on its current frame; bursts fired while paused wait as well.

###### Returns

`void`

##### reset()

> **reset**(): `void`

Stop All Bursts and Clear Canvas.

###### Returns

`void`

##### resume()

> **resume**(): `void`

Resume After pause().

###### Returns

`void`

## Type Aliases

### Cloneable

> **Cloneable**\<`T`\> = `T` *extends* (...`args`) => `unknown` ? `never` : `T` *extends* `string` \| `number` \| `boolean` \| `null` \| `undefined` ? `T` : `T` *extends* `ImageBitmap` ? `T` : `T` *extends* `CanvasImageSource` \| `Path2D` ? `never` : `T` *extends* `Element` ? `T` : `{ [K in keyof T]: Cloneable<T[K]> }`

Worker-Safe Version of an Option Type.
Recursively removes everything `postMessage` cannot copy into a worker: functions (hooks, easing functions,
custom draw), `Path2D` and DOM image sources. `ImageBitmap`s and URL strings stay; plain `Element` origins
stay too because the main thread measures them before posting.

#### Type Parameters

##### T

`T`

***

### WorkerCreateOptions

> **WorkerCreateOptions** = `Omit`\<[`CreateOptions`](#createoptions), `"defaults"` \| `"frameScheduler"`\> & `object`

Options for a Worker Instance.

#### Type Declaration

##### defaults?

> `readonly` `optional` **defaults?**: [`WorkerFireOptions`](#workerfireoptions)

Instance Default Burst Options (worker-safe).

###### Default Value

`{}`

##### workerUrl?

> `readonly` `optional` **workerUrl?**: `string` \| `URL`

Worker Script URL.
With a bundler the worker is created from an inlined script (a `blob:` URL), downloaded only when the first
worker instance is created. The `<script>` build (`konfeti.iife.js`) loads `konfeti.worker.js` from its own
folder instead. Set this to a self-hosted copy of `konfeti/konfeti.worker.js` when your Content-Security-Policy does
not allow `worker-src blob:`, or when the script build is served without the worker file next to it.

###### Default Value

inlined worker (bundlers) / `konfeti.worker.js` next to the script (`<script>` build)

###### Example

```ts
createWorker(canvas, { workerUrl: "/vendor/konfeti.worker.js" });
```

#### Example

```ts
const stage = createWorker(canvas, {
  maxParticles: 3000,
  defaults: { paper: { colors: ["gold", "white"] } },
});
```

***

### WorkerEmitOptions

> **WorkerEmitOptions** = `Omit`\<[`WorkerFireOptions`](#workerfireoptions), `"particleCount"` \| `"origin"` \| `"emission"` \| `"formation"`\> & `object`

Worker-Safe Continuous Emitter Options.
The worker version of `EmitOptions`: every worker-safe fire setting plus `rate` and `follow`. What the
emitter follows is measured on the main thread and sent to the worker.

#### Type Declaration

##### follow?

> `readonly` `optional` **follow?**: [`EmitterTarget`](#emittertarget)

Emission Point: an element, `"pointer"` or a normalized point.

###### Default Value

`{ x: 0.5, y: 0.6 }`

##### rate

> `readonly` **rate**: `number`

Emission Rate.
Particles per second; must be a positive, finite number.

###### Remarks

Unit: particles per second.

#### Example

```ts
const stage = createWorker(canvas);
const trail = stage.emit({ rate: 80, follow: "pointer", spread: 360 });
```

***

### WorkerFireInput

> **WorkerFireInput** = [`WorkerFireOptions`](#workerfireoptions) \| readonly [`WorkerFireOptions`](#workerfireoptions)[]

One Worker Burst or Several Worker Bursts Fired Together.

***

### WorkerFireOptions

> **WorkerFireOptions** = [`Cloneable`](#cloneable)\<`Omit`\<[`FireOptions`](#fireoptions), keyof [`BurstHooks`](#bursthooks) \| `"shapes"` \| `"physics"`\>\> & `object`

Burst Options for a Worker Instance.
`FireOptions` minus what cannot run inside a worker: hooks, function-valued options (custom easings),
`Path2D` paths, DOM image elements, shapes from `defineShape()` and modules from `definePhysics()`.
Use named easings, SVG path strings and image URLs or `ImageBitmap`s instead.

#### Type Declaration

##### physics?

> `readonly` `optional` **physics?**: [`Cloneable`](#cloneable)\<[`BuiltinPhysicsOptions`](#builtinphysicsoptions)\>

Motion Physics (built-in modules only).

##### shapes?

> `readonly` `optional` **shapes?**: readonly [`Cloneable`](#cloneable)\<[`BuiltinShapeOptions`](#builtinshapeoptions)\>[]

Shape Mix (built-in shapes only).

###### Default Value

`[{ type: "paper" }]`

#### Example

```ts
const stage = createWorker(canvas);
stage.fire({ particleCount: 200, paper: { fadeOut: { easing: "easeInQuad" } } });
```

***

### WorkerStats

> **WorkerStats** = `object`

Worker Instance Counters.
Hooks cannot run inside a worker, so a worker instance counts these itself (see
`WorkerKonfetiInstance.getStats()`). Updated a few times per second while particles are alive.

#### Properties

##### completed

> `readonly` **completed**: `number`

Bursts that Finished Since the Instance Was Created.

##### died

> `readonly` **died**: `number`

Particles that Died Since the Instance Was Created.

##### live

> `readonly` **live**: `number`

Live Particles Right Now.

##### spawned

> `readonly` **spawned**: `number`

Particles Spawned Since the Instance Was Created.

## Functions

### createWorker()

> **createWorker**(`canvas?`, `options?`): [`WorkerKonfetiInstance`](#workerkonfetiinstance)

Create Worker Instance.
Simulation and drawing move to a Web Worker (the canvas becomes an `OffscreenCanvas`), so confetti stays
smooth while the page is busy. Falls back to the main thread when `OffscreenCanvas` is unsupported.
Options must be worker-safe: no hooks, easing functions, `Path2D`, DOM images or `defineShape` /
`definePhysics` extensions (see `WorkerFireOptions`).

#### Parameters

##### canvas?

`HTMLCanvasElement` \| `null`

Target Canvas (`null` or omitted creates a fullscreen overlay)

##### options?

[`WorkerCreateOptions`](#workercreateoptions)

Worker Instance Options

#### Returns

[`WorkerKonfetiInstance`](#workerkonfetiinstance)

Worker Instance

#### Example

```ts
import { createWorker } from "konfeti/worker";

const stage = createWorker(document.querySelector("canvas"));
stage.fire({ particleCount: 400, spread: 360 });
stage.isWorker(); // true where OffscreenCanvas is supported
```

#### Remarks

Lives in its own entry (`konfeti/worker`), so apps that never render in a worker carry none of
this code.