emoji-blast

emoji-blast is a lightweight library that provides ways to blast emojis in a web page. It can be embedded in virtually any web app.

Getting Started

Quick Bundler Start

If you’re writing JavaScript or TypeScript with a bundler, first install the emoji-blast package as a dependency:

npm i emoji-blast

You can then import it in your code to access its emojiBlast and emojiBlasts functions:

import { emojiBlast, emojiBlasts } from "emoji-blast";

emojiBlast(); // Just one blast, please.
emojiBlasts(); // Commence blasting!

If you’re using ESM or any modern JavaScript bundler or framework, such as ESBuild, Vite, or Webpack, this should just work. ✨

See emoji-blast API for more details.

Quick HTML Start

If you’re directly writing an .html document, you can plop this 👇 at the end of your <body>:

<script async src="https://unpkg.com/emoji-blast/dist/now.js"></script>

That 👆 loads emoji-blast soon after your page loads and starts emojiBlasts() as soon as it can.

👌.

You’ll probably want a little more fine-grained control over when the blasts occur. Use this 👇 alternate script to create global emojiBlast and emojiBlasts functions:

<script src="https://unpkg.com/emoji-blast/dist/global.js"></script>
<script>
  emojiBlast(); // Just one blast, please.
  emojiBlasts(); // Commence blasting!
</script>

See emoji-blast API for more details.

API

emoji-blast exports two functions:

emojiBlast: Triggers a single blast of emojis.
emojiBlasts: Starts firing emojiBlast() at random locations on an setInterval.

`emojiBlast`

import { emojiBlast } from "emoji-blast";

emojiBlast();

Each emojiBlast() by default causes a fireworks-like blast of random emoji to be placed around a random location on your page. The blasts each contain around a dozen emoji, each of which are animated in JavaScript to:

Start with a random horizontal velocity and random upward vertical velocity
Move along the page as if affected by velocity and preserving inertia

After an emoji is completely hidden or out of bounds, it is removed from the page.

`emojiBlast` Options

emojiBlast is highly configurable. The following may be passed to both via configuration objects.

`className`

Type: string or () => string

CSS class name to add to all emoji elements. Defaults to "emoji-styles".

emojiBlast({
  className: "my-emoji-styles",
});

Whenever a new className is passed to emoji-blast, a new <style> element is created to add general emoji styles for that class. See styles.ts.

`container`

Type: Element or () => Element

Element container to append elements into. Defaults to a new <div /> inserted as a first child of document.body.

emojiBlast({
  container: document.getElementById("fun"),
});

`emojiCount`

Type: number or () => number

How many emojis to create per blast. Defaults to random number between 14 and 28.

Creating 9001 emoji per blast:

emojiBlast({
  emojiCount: 9001,
});

Creating a random number between 100 and 200 per blast:

emojiBlast({
  emojiCount: () => Math.random() * 100 + 100,
});

`events`

Type: { onClick?: (data: EmojiEventData) => void; }

Handlers for user interactions with individual emojis. Defaults to an onClick that pushes up the emoji up just a little bit.

emojiBlast({
  events: {
    onClick({ actor, event }) {
      actor.update({
        opacity: 1,
        velocity: {
          y: actor.velocity.y / 2 - 15,
        },
      });
    },
  },
});

The EmojiEventData interface contains:

actor: EmojiActor: The individual actor being interacted with.
event: Event: The original triggering DOM event.

`emojis`

Type: string[] or () => string[]

List of allowed emojis to randomly choose from for each blast. The default list of emojis is in emojis.ts; it excludes emojis with dubious reputations such as 💩 and 🍆.

Found an emoji not supposed to be in that list? Please file an issue!

Always choosing the 💖 emoji:

emojiBlast({
  emojis: ["💖"],
});

Allowing any of several wonderful heart emojis for each emoji within a blast:

emojiBlast({
  emojis: ["💖", "💕", "💗", "💓", "💝"],
});

`physics`

Runtime change constants for emoji element movements. These default to a sane set of ranges for random numbers that give the appearance of fireworks-like blasts.

These values must be passed in as numbers, with defaults as (value) here:

framerate (60): Expected frames per second to adjust position and velocity changes by.
gravity (0.35): How much to increase y-velocity downward each tick.
rotationDeceleration (0.98): How much to decrease rotation amount each tick.

These values may be randomized, so you can provide them as a const number or { max: number, min: number } for a random integer within, inclusive. Defaults are ([min, max]) here:

fontSize ([14, 28]): Individual emojis’ font size range.
initialVelocities:
- rotation ([-7, 7]): Range of initial rotation amount.
- x ([-7, 7]): Range of initial horizontal velocity.
- y ([-14, -11.7]): Range of initial vertical velocity.
rotation ([-45, 45]): Individual emojis’ initial rotation range.

These values are optional:

preserveOutOfBounds: Whether to skip removing emojis that move outside of the visible screen.
opacityDelay: How much to slow down the (time elapsed / framerate) opacity reduction each tick (recommendation: 100 to fade out over a few seconds).

Causing emojis to spin wildly out of control:

emojiBlast({
  physics: {
    initialVelocities: {
      rotation: {
        max: 14,
        min: -14,
      },
    },
    rotationDeceleration: 1.01,
  },
});

Inverting gravity:

emojiBlast({
  physics: {
    gravity: -0.35,
    initialVelocities: {
      y: {
        max: 14,
        min: 11.7,
      },
    },
  },
});

Alternately, the defaultPhysics object is exported, so you can base your physics constants off it:

import { emojiBlasts, defaultPhysics } from "emoji-blast";

emojiBlast({
  physics: {
    gravity: -defaultPhysics.gravity,
    initialVelocities: {
      y: {
        max: -defaultPhysics.initialVelocities.max,
        min: -defaultPhysics.initialVelocities.min,
      },
    },
  },
});

`position`

Type: { x: number, y: number } or () => { x: number, y: number }

How to determine where to place blasts of emojis around the page. These are absolutely positioned midpoints to center the blasts around. They’re used directly as left and top CSS properties. You can provide a static object or a function to create one.

The default position chooses integers within the page:

emojiBlast({
  position: () => ({
    x: Math.random() * innerWidth,
    y: Math.random() * innerHeight,
  }),
});

Always exploding from a fixed position:

emojiBlast({
  position: {
    x: 35,
    y: 35,
  },
});

Exploding emoji around your favorite element on the page:

const element = document.querySelector("#my-face");

emojiBlast({
  position() {
    // https://stackoverflow.com/questions/1480133
    const offset = cumulativeOffset(element);

    return {
      x: offset.left + element.clientWidth / 2,
      y: offset.top + element.clientHeight / 2,
    };
  },
});

`process`

Type: (element: Element) => void

Processes each element just before it’s appended to the container. Useful if you’d like to apply custom attributes, class names, or styles to your elements.

Adding an .emoji class to each element:

emojiBlast({
  process(element) {
    element.className = "emoji";
  },
});

`uniqueness`

Type: number or () => number

How many different types of emojis are allowed within a blast. Each blast will evaluate this to a number, U, and choose the first U emojis from a shuffled variant of the emojis list. If U > emojis.length, it will be ignored.

uniqueness defaults to Infinity.

Allowing only one emoji type per blast:

emojiBlast({
  uniqueness: 1,
});

Allowing one more emoji type per blast each blast:

let count = 0;

emojiBlast({
  uniqueness() {
    count += 1;
    return count;
  },
});

`emojiBlasts`

import { emojiBlasts } from "emoji-blast";

emojiBlasts();

emojiBlasts is used to start firing emojiBlast() calls every second or so on an interval.

It returns an object containing:

A blast function that manually triggers a blast
A cancel function that can cancel any pending work

// Commence blasts!...
const { stop } = emojiBlasts();

// ...but stop after ten seconds.
setTimeout(stop, 10000);

`emojiBlasts` Options

emojiBlasts can take in all of emoji-blast options.

Additionally, the following configurations are exclusively for emojiBlasts:

`interval`

Type: number or () => number

How frequently to create blasts. Passed to scheduler as the delay (typically in milliseconds) before each blast.

Pass a number to always delay that much. Pass a function for it to be called immediately for the delay before the first blast, then again as each blast is started to schedule the next blast.

The default interval is a function that returns 0 the first time for an immediate blast, then a random number in [700, 2100] subsequent times.

As quickly as setInterval can fire (this will probably crash your browser!):

emojiBlasts({
  interval: 0,
});

Once a second:

emojiBlasts({
  interval: 1000,
});

0ms delay the first blast, then 1000ms delay each subsequent blast:

let scheduled = false;

emojiBlasts({
  interval() {
    if (!scheduled) {
      scheduled = true;
      return 0;
    }

    return 1000;
  },
});

`scheduler`

Type: (action: () => void, delay: number) => number

Schedules the next blast to occur. This defaults to setTimeout, which is why interval is typically treated as milliseconds.

emojiBlasts({
  scheduler(action, delay) {
    console.log(`Will emoji in ${delay} ms!`);
    setTimeout(action, delay);
  },
});

emoji-blast

Getting Started

Quick Bundler Start

Quick HTML Start

API

emojiBlast

emojiBlast Options

className

container

emojiCount

events

emojis

physics

position

process

uniqueness

emojiBlasts

emojiBlasts Options

interval

scheduler

`emojiBlast`

`emojiBlast` Options

`className`

`container`

`emojiCount`

`events`

`emojis`

`physics`

`position`

`process`

`uniqueness`

`emojiBlasts`

`emojiBlasts` Options

`interval`

`scheduler`