Skip to content

alexandermendes/vue-confetti

Repository files navigation

vue-confetti

npm version semantic-release

🎉 A Vue component for dropping confetti 🎉

Example animation

View the demo

Installation

yarn add vue-confetti

Usage

<template>
  <main>
    <button @click="start">Start</button>
    <button @click="stop">Stop</button>
    <button @click="love">Show some love</button>
  </main>
</template>

<script>
  import Vue from 'vue'
  import VueConfetti from 'vue-confetti'

  Vue.use(VueConfetti)

  export default {
    methods: {
      start() {
        this.$confetti.start();
      },

      stop() {
        this.$confetti.stop();
      },

      love() {
        this.$confetti.update({
          particles: [
            {
              type: 'heart',
            },
            {
              type: 'circle',
            },
          ],
          defaultColors: [
            'red',
            'pink',
            '#ba0000'
          ],
        });
      }
    }
  }
</script>

Usage with Nuxt

As this plugin relies on browser globals, such as window, it will not work when server-side rendered. The following example shows how to get this to add as a client-side only plugin with Nuxt.

Register vue-confetti in your Nuxt plugins folder (e.g. at your-repo/plugins/vue-confetti):

import Vue from 'vue';
import VueConfetti from 'vue-confetti';

Vue.use(VueConfetti);

Register the plugin in your Nuxt config:

export default {
  plugins: [
    { src: '~/plugins/vue-confetti.js', mode: 'client' },
  ],
};

Configuration

The following options can be passed to $confetti.start() or $confetti.update():

Property Type Description Default
particles Array The settings for each particle type (see below). 10
defaultType String The default particle type. 'circle'
defaultSize Number The default size of all particles (should be a positive number). 10
defaultDropRate Number The default speed at which the particles fall. 10
defaultColors Array The default particle colors. ['DodgerBlue', 'OliveDrab', 'Gold', 'pink', 'SlateBlue', 'lightblue', 'Violet', 'PaleGreen', 'SteelBlue', 'SandyBrown', 'Chocolate', 'Crimson']
canvasId String The ID for a custom canvas element (the default is to append a canvas to the <body> element). null
canvasElement HTMLCanvasElement A custom canvas element (the default is to append a canvas to the <body> element). null
particlesPerFrame Number The number of particles to drop per animation frame. 2
windSpeedMax Number The maximum wind speed (disabling the wind by setting to 0 can be useful for slower drop rates). 1

The following options can be passed to each item in particles:

Property Type Description Default
type String The type of particle ('circle', 'rect', 'heart' or 'image'). 'circle'
size Number The size of the particles (should be a positive number). 10
dropRate Number The speed at which the particles fall. 10
colors Array The particle colors. ['DodgerBlue', 'OliveDrab', 'Gold', 'pink', 'SlateBlue', 'lightblue', 'Violet', 'PaleGreen', 'SteelBlue', 'SandyBrown', 'Chocolate', 'Crimson']
url String The path to a custom image or SVG to use as the particle. Note that type must be set to image. null

Examples

Red and pink hearts:

$confetti.start({
  particles: [
    {
      type: 'heart',
    }
  ],
  defaultColors: [
    'red',
    'pink',
    '#ba0000',
  ],
});

Custom image:

$confetti.start({
  particles: [
    {
      type: 'image',
      url: 'http://placekitten.com/50/50',
    },
  ],
});

Custom canvas:

By id:
$confetti.start({
  canvasId: 'my-custom-canvas',
});
By element reference:
$confetti.start({
  canvasElement: document.getElementById('my-custom-canvas'),
});

Less particles per frame:

$confetti.start({
  particlesPerFrame: 0.25,
});

Multiple particle types:

$confetti.start({
  particles: [
    {
      type: 'heart',
      colors: [
        'red',
        'pink',
      ],
    },
    {
      type: 'circle',
      colors: [
        '#ba0000',
      ],
    },
    {
      type: 'image',
      size: 15,
      url: 'http://example.org/my-icon.svg',
    },
  ],
  defaultDropRate: 5,
  defaultSize: 5,
});

Development

The following scripts are available for local development:

# test
yarn run test

# run with webpack watch
yarn run dev

# build for production
yarn run build

# serve the demo page (watch for changes from another terminal)
yarn run demo

Note that vue-confetti enforces conventional commits to help automate the release process. Whenever code is merged into master the next semantic version number is automatically determined, a changelog generated and the release published.