@neoconfetti/solid

Let's party 🎊🎊 with Solid! @neoconfetti/solid allows you to show an awesome confetti explosion on your page, with SolidJS!

Features

• 🤏 Tiny - 1.55KB min+br.
• 🐇 Simple - Quite simple to use, and effectively no-config required!
• 🧙‍♀️ Elegant - Directive use:confetti.
• 🗃️ Customizable - Offers tons of options that you can modify to get different behaviors.
• 🖥️ SSR friendly - Works seamlessly in SolidStart!

Installing

# pnpm
pnpm add @neoconfetti/solid

# npm
npm install @neoconfetti/solid

# yarn
yarn add @neoconfetti/solid

Usage

Basic usage:

import { createConfetti } from '@neoconfetti/solid';

function App() {
	const { confetti } = createConfetti();

	return <div use:confetti />;
}

Customizing behavior with options:

<div use:confetti={{ particleCount: 200, force: 0.3 }} />

Props

There's tons of options available for this package. All of them are already documented within the code itself, so you'll never have to leave the code editor.

particleCount

Number of confetti particles to create.

type: number

Default value: 150

Example:

<div use:confetti={{ particleCount: 200 }} />

particleSize

Size of the confetti particles in pixels

type: number

Default value: 12

Example:

<div use:confetti={{ particleSize: 20 }} />

particleShape

Shape of particles to use. Can be mix, circles or rectangles

mix will use both circles and rectangles circles will use only circles rectangles will use only rectangles

type: 'mix' | 'circles' | 'rectangles'

Default value: 'mix'

Example:

<div use:confetti={{ particleShape: 'circles' }} />

duration

Duration of the animation in milliseconds

type: number

Default value: 3500

Example:

<div use:confetti={{ duration: 5000 }} />

colors

Colors to use for the confetti particles. Pass string array of colors. Can use hex colors, named colors, CSS Variables, literally anything valid in plain CSS.

type: Array<string>

Default value: ['#FFC700', '#FF0000', '#2E3191', '#41BBC7']

Example:

<div use:confetti={{ colors: ['var(--yellow)', 'var(--red)', '#2E3191', '#41BBC7'] }} />

force

Force of the confetti particles. Between 0 and 1. 0 is no force, 1 is maximum force. Will error out if you pass a value outside of this range.

type: number

Default value: 0.5

Example:

<div use:confetti={{ force: 0.3 }} />

stageHeight

Height of the stage in pixels. Confetti will only fall within this height.

type: number

Default value: 800

Example:

<div use:confetti={{ stageHeight: 500 }} />

stageWidth

Width of the stage in pixels. Confetti will only fall within this width.

type: number

Default value: 1600

Example:

<div use:confetti={{ stageWidth: 500 }} />

destroyAfterDone

Whether or not destroy all confetti nodes after the duration period has passed. By default it destroys all nodes, to free up memory.

type: boolean

Default value: true

Example:

<div use:confetti={{ destroyAfterDone: false }} />

TypeScript

This library ships with proper TypeScript typings, for the best Developer Experience, whether authoring JS or TS.

However, if you destructure the result of createConfetti() to something other than confetti, you will get errors. If you rename it, like this:

import { createConfetti } from '@neoconfetti/solid';

const { confetti: myCustomConfetti } = createConfetti();

<div use:myCustomConfetti />;

It will give an error

Property 'use:myCustomConfetti' does not exist on type 'HTMLAttributes<HTMLDivElement>'.

In that case, you have to manually add to your globals.d.ts file this snippet:

import { ConfettiOptions } from '@neoconfetti/solid';
import 'solid-js';

declare module 'solid-js' {
	namespace JSX {
		interface Directives {
			myCustomConfetti: ConfettiOptions;
		}
	}
}

Fine-grained reactivity

Changing the options will destroy the existing confetti mid-flight, and create a new one with the new options. Exception: If particlesCount isn't changed, and properties like colors or particleShape is changed, the confetti particles will change their colors or shape mid-flight.

Performance

This library functions by creating 2 DOM nodes for every single confetti. By default, if the particlesCount is set to 150, it will create 300 nodes. This is a lot of nodes. For most devices, these many nodes are not a big issue, but I recommend checking your target devices' performance if you choose to go with a higher number, like 400 or 500.

Also, after the specified duration, all the confetti DOM nodes will be destroyed. This is to free up memory. If you wish to keep them around, set destroyAfterDone to false.

Future plans

Right now, if you look at the syntax, it looks like this:

import { createConfetti } from '@neoconfetti/solid';

const { confetti } = createConfetti();

<div
	use:confetti={
		{
			/* options */
		}
	}
/>;

If you look closely, the createConfetti is completely useless. It could've just been:

import { confetti } from '@neoconfetti/solid';

<div
	use:confetti={
		{
			/* options */
		}
	}
/>;

So why an extra function? Because use:confetti, after compiled, is just treated as a string. This means, the typescript compiler/rollup will just remove the import named confetti completely, breaking the whole code. Hence a wrapper function is needed.

In future, if SolidJS introduces a mechanism similar to Svelte's actions, I'll be able to get rid of that extra call entirely! So if you find this syntax a little more verbose, bear with me, it might become better :)

Credits

This library is the port of the amazing react-confetti-explosion package, just 10X smaller and faster. All the logic is from that package only, optimisation and Svelte code are mine 😉

License

MIT License © Puru Vijay