Floating Icons

An easy to use package to create an engaging animation effect with emojis or icons that float out and up from a specified target element on your webpage.

This effect is perfect for adding fun and interactive visual effects to your project.

If you find this package helpful please consider giving it a star on GitHub ⭐

Live demos

Live web demo →

javascript / typescript:

React:

Vue 3:

Svelte:

Quick links

Live demos
Features
Installation
Basic usage
Basic usage with React
Options
How to customize the behavior
How to use with existing element or with fixed screen coordinates
How to use with your own html content
Methods

Features

• Animate multiple icons or emojis or any other HTML elements with configurable properties.
• Control amount of elements, density, distance, delay, duration, size, and rotation of the elements.
• Randomized rendering based on defined probabilities.
• Support for various CSS units for position, speed and animation.
• Supports positioning on existing HTML elements or via specifiying fixed x & y values (like position:fixed).
• Framework agnostic - works with any typescript and plain javascript project. (React, Vue, Svelte, Solid, ...).
• Super performat animations using CSS animations.
• 0 dependencies, less than 4kb when minified and gzipped.

Installation

Simple installation via common package managers:

npm:

npm install floating-icons

pnpm:

pnpm install floating-icons

yarn:

yarn add floating-icons

Or install manually by copying the code from the FloatingIcons.js and pasting it to your project.

Basic usage

HTML:

<button id="#my-btn">Click me!</button>

Script:

import useFloatingIcons from "floating-icons";

const myBtn = document.querySelector("#my-btn");
myBtn.addEventListener("click", () => {
  useFloatingIcons({
    target: "#my-btn",
    /* options */
  });
});

Options

Here's a list of all the options. Please read below the table for further explanation of how this package works and how you can customize its behaviour to your liking.

Option	Description	Type	Required	Default value
target	The element or screen coordinates on which to render the effect. The effect will be centered in the specified target.	HTMLElement / CSS Selector / {x: '100px', y:'200px'}	✅	null
elements	Array of elements to render. Random element will be rendered based on probability / totalProbability.	{ content: string / HTMLElement, probability: number}[]		[{ content: "❤️", probability: 3 },{ content: "😄", probability: 1 },{ content: "👍🏻", probability: 1 },{ content: "✌🏻", probability: 1 }]
debug	If "true" renders borders on all elements. helpfull for development.	boolean		false
density	Controls the density in which the elements will render. Accepts a range between 0-1. 1 being most dense.	number		0.6
distanceToTravel	The distance elements will travel before fading out.	Any valid css length value ("10px", "2rem", "5vw", ...)		"100px"
minDelay	Minimum delay (in ms) to start animating an element. Each element gets a random animation delay value within the range	number		0
maxDelay	Maximum delay (in ms) to start animating an element. Each element gets a random animation delay value within the range	number		800
minDuration	Minimum duration (in ms) of the animation. Each element gets a random animation duration value within the range	number		500
maxDuration	Maximum duration (in ms) of the animation. Each element gets a random animation duration value within the range	number		1500
minElementCount	Minimum amount of elements to render. A random amount will be rendered between the min and max range	number		8
maxElementCount	Maximum amount of elements to render. A random amount will be rendered between the min and max range	number		12
minRotation	Minimum rotation per element (in degrees). A random value within the range will be selected for each element	number		-15
maxRotation	Maximum rotation per element (in degrees). A random value within the range will be selected for each element	number		15
minSize	Minimum size for a single element. A random value within the range will be selected for each element	Any valid css length value ("10px", "2rem", "5vw", ...)		"20px"
maxSize	Maximum size for a single element. A random value within the range will be selected for each element	Any valid css length value ("10px", "2rem", "5vw", ...)		"40px"
opacity	Maximum opacity for all elements	number / string		1
wiggle	The amount of which elements will wiggle from side to side	Any valid css length value ("10px", "2rem", "5vw", ...)		"10px"
zIndex	The z-index for the containing element	number / string		0

How to customize the behavior

Some of the options have a min and max value (minDelay and maxDelay for example). This means when each element is rendered a random value from the range (min to max) will be assigned.

How to change which emojis (or elements) the function renders

Use the elements option to pass an array of possible elements to render.

import useFloatingIcons from "floating-icons";

useFloatingIcons({
  target: "#my-el",
  elements: [
    { content: "❤️", probability: 3 },
    { content: "😄", probability: 2 },
    { content: "👍🏻", probability: 1 },
    { content: "✌🏻", probability: 1 },
  ],
});

For each item in the array specify the "content" to render and a probability to render the item.

When elements are being rendered a random element item will be selected from the array based on its probability divided by the total probability value.

For the example above theres a 3 / 6 chance a "❤️" will be selected. a 2/6 chance that a "😄" will be selected. and 1/6 chance for the rest of the items.

That means that if you render 6 elements you would most likely get 3 "❤️", 2 "😄", 1, "👍🏻", "✌🏻". Since the selection is random the amounts and their location in the animation will change for each invocation of the function.

This results in an effect that appears new and exciting every time.

How to use with existing element or with fixed screen coordinates

In order to render the effect on an existing element you can specify the elments selector or a reference to the element.

import useFloatingIcons from "floating-icons";

// Using with a selector
useFloatingIcons({
  target: "#my-btn",
});

// Using with an element reference
const myBtn = document.querySelector("#my-btn");
useFloatingIcons({
  target: myBtn,
});

// Using with coordinates (positioned using positin:fixed)
useFloatingIcons({
  target: {
    x: "200px",
    y: "300px",
  },
});

The effect will be rendered in the center on the target element or the specified screen coordinates as shown in the image below.

How to use with your own html content

Instead of using emojis you can specify your own html elements in the elements.content option.

import useFloatingIcons from "floating-icons";

const myFirstHTMLElement = document.querySelector("#my-first-html-element");
const mySecondHTMLElement = document.querySelector("#my-second-html-element");

useFloatingIcons({
  target: "#my-el",
  elements: [
    {
      content: myFirstHTMLElement,
      probability: 1,
    },
    {
      content: mySecondHTMLElement,
      probability: 1,
    },
  ],
});

Methods

destroy: destroys the animation element. this function is called automatically after the animation has finished. You can call it manually if you want to destory the element before the animation is complete.

import useFloatingIcons from "floating-icons";

const floatingIcons = useFloatingIcons({ target: "#my-btn" });

setTimeout(() => {
  floatingIcons.destroy();
}, 1000);

Basic usage with React

import useFloatingIcons from "floating-icons";

export function MyBtn() {
  return (
    <div className="App">
     <button onClick={(e) => {
          useFloatingIcons({
            target: e.currentTarget as HTMLElement,
            debug: false,
            density: 0.6, // range from 0.0 - 1
            distanceToTravel: '100px',
            minDelay: 0, // ms
            maxDelay: 800, // ms
            minDuration: 500, // ms
            maxDuration: 1500, // ms
            minElementCount: 8, // number
            maxElementCount: 12, // number
            minRotation: -15, // degrees
            maxRotation: 15, // degrees
            minSize: '20px',
            maxSize: '40px',
            opacity: 1, // range from 0.0 - 1
            wiggle: '10px', // sizeUnit
            zIndex: 0,
          });
        }}
      >
      Click me!
    </button>
    </div>
  );
}