Vue Confetti Explosion

1.0.2 · active · verified Sun Apr 19

vue-confetti-explosion is a lightweight and performant Vue 3 component designed to create customizable confetti explosion animations. Currently at version 1.0.2, this library is a direct port from popular Svelte and React counterparts, offering a consistent API for triggering celebratory visual effects within Vue applications. It focuses on simplicity and performance, generating a specified number of confetti particles with options for size, duration, color arrays, and explosion force. While it doesn't specify a strict release cadence, updates are likely tied to major Vue 3 ecosystem shifts or bug fixes. A key differentiator is its minimal API and ease of integration into `<script setup>`-style Vue components, making it an ideal choice for adding quick, dynamic visual flair without significant overhead.

Common errors

```
Confetti particles are not fully visible or are cut off.
```
cause A parent container has `overflow: hidden` or a similar CSS property that clips content.

fix Set `overflow: visible` on the CSS of the component's direct or indirect parent container where the confetti should expand.
```
Error: Force prop value must be between 0 and 1.
```
cause The `force` prop was provided a number outside its valid range (0 to 1).

fix Change the `force` prop to a value between 0 and 1 (e.g., `:force="0.75"`).
```
Confetti stops abruptly at the bottom of the screen instead of disappearing naturally.
```
cause The `stageHeight` prop is set too small for the visual space where the confetti should fall.

fix Increase the `stageHeight` prop (e.g., `:stageHeight="1200"`) to allow confetti to fall further down before disappearing from view.

Warnings

gotcha Confetti particles may appear cut off or confined if the parent container does not have `overflow: visible` applied, preventing them from spreading across the intended area.
Fix: Ensure the parent container's CSS includes `overflow: visible` to allow particles to spread freely and fully animate.
gotcha Particles might visibly land and accumulate on a 'floor' within the stage if the `stageHeight` prop is not sufficient, instead of naturally disappearing off-screen.
Fix: Adjust the `stageHeight` prop to a larger value (e.g., `:stageHeight="1000"`) to ensure particles fall out of view gracefully.
gotcha The `force` prop, which controls the intensity of the explosion, must be a numerical value between 0 and 1. Providing a value outside this range will result in an error and prevent the explosion.
Fix: Always ensure `force` is set to a value like `0.5` (default) or any float between `0` and `1` (e.g., `:force="0.75"`).
gotcha While the Svelte version of this library (from which `vue-confetti-explosion` is ported) supports `--x` and `--y` CSS variables for positional styling, these 'Style Props' are explicitly *not* implemented in this Vue 3 component.
Fix: Do not attempt to use `--x` or `--y` CSS variables for positioning on the `ConfettiExplosion` component; they are not supported by this Vue component and will have no effect.

Install

npm install vue-confetti-explosion npm
yarn add vue-confetti-explosion yarn
pnpm add vue-confetti-explosion pnpm

Imports

ConfettiExplosion

wrong:

import { ConfettiExplosion } from 'vue-confetti-explosion';

correct:

import ConfettiExplosion from 'vue-confetti-explosion';

The component is a default export, use `import ConfettiExplosion from ...` for ESM.

ConfettiExplosion (CommonJS)
wrong:
```
const ConfettiExplosion = require('vue-confetti-explosion');
```
correct:
```
const ConfettiExplosion = require('vue-confetti-explosion').default;
```
While primarily for ESM, CommonJS environments require accessing the `.default` property for default exports.

Quickstart

Demonstrates how to programmatically trigger a confetti explosion on a button click, ensuring the component re-renders for each new effect with custom options.

import { nextTick, ref } from "vue";
import ConfettiExplosion from "vue-confetti-explosion";

const visible = ref(false);

const explode = async () => {
  visible.value = false;
  await nextTick();
  visible.value = true;
};

<template>
  <div>
    <button @click="explode">Trigger Confetti</button>
    <ConfettiExplosion v-if="visible" :particleCount="200" :duration="4000" :force="0.6" :colors="['#F06292', '#BA68C8', '#64B5F6', '#81C784', '#FFD54F']"/>
  </div>
</template>

view raw JSON →