Web

In this guide, we demonstrate how to use the Lordicons in a web page project. To make the entire process easier, we have prepared a player (a custom element) that can be integrated into any web project.

We love open-source, and whenever possible, we strive to give back to the community. The player we've prepared is available for free as part of the NPM package. Additionally, we provide a repository with the complete source code.

<script src="https://cdn.lordicon.com/lordicon.js"></script>

<lord-icon
    src="https://cdn.lordicon.com/lewtedlh.json"
    trigger="hover"
    stroke="light"
    state="hover-pinch"
    colors="primary:#3080e8,secondary:#b4b4b4"
    style="width:250px;height:250px">
</lord-icon>

The simplest way to integrate the Lordicon player into a website is by loading a JavaScript script, which will automatically display icons wherever you've embedded the HTML <lord-icon> tag.

You can obtain sample code for a specific icon by using the embed HTML function on our website. This method is ideal for rapid prototyping, where performance and control over the loading process are not critical.

In the <head> section, you should load the lordicon.js script. This script should only be loaded once and is independent of the selected icon. The script link may change with the release of a new player version, and using new icons may require its updated version.

<script src="https://cdn.lordicon.com/lordicon.js"></script>

You should place the <lord-icon> tag where you want the icon to appear.

<lord-icon
    src="https://cdn.lordicon.com/lbjtvqiv.json"
    trigger="hover">
</lord-icon>

Simple usage

Click to see a straightforward integration of the player with a web page directly in your browser.

As you can see, in the simplest integration, adding animated, custom icons created with a graphical editor is as easy as copying and pasting a few lines of code.

The optimal way to integrate the player with a web application is to use the @lordicon/element package we've prepared. When integrating our player, we recommend using a module bundler like Webpack, Rollup or another similar tool.

Installation:

npm install @lordicon/element

Code:

import { defineElement } from "@lordicon/element";

// define "lord-icon" custom element with default properties
defineElement();

HTML:

<lord-icon trigger="hover" src="/my-icon.json"></lord-icon>

Recommended usage

Click to view a live integration of the player with a website using the @lordicon/element package in your browser.

Our custom element <lord-icon> not only allows you to easily embed an icon on a web page but also dynamically customize it using HTML.

We support the following attributes here (all values are optional):

Attribute	Description
src	URL path to the icon JSON file. Example: `"/icons/heart.json"`
colors	Color palette in key-value format. Use color names from the icon's palette as keys. Example: `"primary:#ff0000,secondary:#00ff00"`
stroke	Line thickness for supported icons. Available values: `"light"`, `"regular"`, `"bold"`
speed	Animation playback speed multiplier. Default is `1`. Use `0.5` for half speed, `2` for double speed, etc.
trigger	Animation trigger type. Available: `"in"`, `"click"`, `"hover"`, `"loop"`, `"loop-on-hover"`, `"morph"`, `"boomerang"`, `"sequence"`
target	CSS selector for the element that should receive trigger events instead of the icon itself
state	Specific animation state to play. Icons can have multiple built-in animations
loading	Loading strategy for performance optimization. Available: `"lazy"` (viewport), `"interaction"` (user action), `"delay"` (timed)

In addition to managing attributes, users can customize icons (to a limited extent) using CSS variables. Variables allow for dynamic color swapping of icons, opening the door to easily implement features like dark mode/light mode switching or icon color changes through interaction without the need to write JavaScript code.

--lord-icon-primary: red;
--lord-icon-secondary: blue;

Note: 'primary' and 'secondary' above are example color names. Different icons may support different colors.

If you want the icon to take on a single color based on the text of the parent element, you can assign it a dedicated class, 'current-color':

<lord-icon class="current-color" trigger="hover" src="/my-icon.json"></lord-icon>

The provided custom element comes with multiple built-in triggers. Triggers define how the icon will interact with the web page. Additionally, triggers can be instructed to follow a specified element. Here's an example of an icon that will animate when the mouse hovers over the parent button:

<div class="btn">
    <lord-icon target=".btn" trigger="hover" src="/my-icon.json"></lord-icon>
</div>

Working with the element, depending on the project's needs, can go far beyond simply embedding an icon on a web page. We provide access to an API where animation, various icon properties, and supported triggers can be fully controlled by the programmer. This allows for achieving intriguing effects where interaction with icons can add value to the project being implemented.

For the loaded icon, you gain access to the player instance:

const element = document.querySelector("lord-icon");

// the player is ready
element.addEventListener("ready", () => {
    element.playerInstance.play();
});

Supported methods:

Method	Description
init()	Initialize the player (called automatically by default).
destroy()	Destroy the player and release resources.
play()	Play the animation. Note: A finished animation can't be played again from the last frame. However you can change the direction of the animation or replay it from the beginning.
playFromStart()	Play the animation from the beginning.
pause()	Pause the animation.
stop()	Stop the animation.
seek(frame)	Go to the exact frame.
seekToStart()	Go to the first animation frame.
seekToEnd()	Go to the last animation frame.
addEventListener(name, callback)	Register event handler. Supported event names: `'ready'`, `'complete'`, `'frame'`, `'refresh'`.
removeEventListener(name, callback)	Remove event handler(s)

Supported properties:

Property	Description
colors	Proxy for color manipulation (e.g., player.colors.primary = '#fff').
stroke	Stroke width (number or preset).
state	Current animation state (string).
speed	Playback speed.
direction	Playback direction (1 or -1).
loop	Looping (boolean).
frame	Current frame (number).
playing	Whether animation is playing (boolean).
ready	Whether player is ready (boolean).
availableStates	List of available states.
frameCount	Total number of frames in the animation (number).
duration	Duration of the animation in seconds (number).
properties	Get or set multiple properties at once. Setter: Any property not provided will be reset to its default value (overwrites all properties). Getter: Returns the current properties object.
segment	Gets the current segment of the animation as [start, end] frame numbers.
lottieInstance	Access to the underlying internal Lottie player instance.
lottieProperties	Array of customizable properties for the icon.

In the included repository and examples, we demonstrate how to use the low-level player.

Triggers

Discover all the built-in animation triggers available.

Simple usage

Simple usage

Recommended usage

Recommended usage

API

Custom Element

Player

Examples

Best practices

Icon hosting

Minify

Optimizations