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.

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>

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. This package should be used in pair with lottie-web. When integrating our player, we recommend using a module bundler like Webpack, Rollup or another similar tool.

Installation:

npm install @lordicon/element lottie-web

Code:

import lottie from "lottie-web";
import { defineElement } from "@lordicon/element";

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

HTML:

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

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	Link to the icon.
colors	Assign colors in text notation, where the first part is the color name and the second part is its value. For example: "outline:#121331,primary:#3a3347".
stroke	Thickness for supported icons, for example: "light," "regular," "bold".
trigger	The trigger name to be assigned to the icon. By default, we support: "in," "click," "hover," "loop," "loop-on-hover," "morph," "boomerang," "sequence."
target	Query selector for the element on which events will be listened.
state	Choose an animation for the icon (a single icon in Lordicon can have multiple built-in animations - you can see which animations an icon supports in our editor).
loading	The method by which the icon will be loaded. It allows for delayed loading of the icon. Acceptable values: "lazy," "interaction."
icon	Icon name to load. This applies to those who want to load icons in conjunction with the API.

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();
});

// the animation is complete
element.addEventListener("complete", () => {
    element.playerInstance.direction *= -1;
    element.playerInstance.play();
});

Supported methods:

Method	Description
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.
playFromBeginning()	Play the animation from the beginning.
pause()	Pause the animation.
stop()	Stop the animation.
goToFrame(frame)	Go to the exact frame.
goToFirstFrame()	Go to the first animation frame.
goToLastFrame()	Go to the last animation frame.
addEventListener(name, callback)	Start listening for an event. Supported events: "ready", "refresh", "complete", "frame".
removeEventListener(name, callback)	Stop listening for an event.

Supported properties:

Property	Description
properties	Access to read or modify multiple properties at once. Resets to default any properties that are not provided.
colors	This property allows you to discover customizable colors or update them within a processed icon.
stroke	The 'stroke' property gives you the value of the icon's stroke width.
state	This property allows you to control the state (motion type) of the icon. States enable switching between multiple animations built into a single icon file.
speed	This property allows you to control the speed of the icon animation.
frame	Access the player frame. You can manually control the animation playback by changing this frame.
direction	The 'direction' property lets you influence the direction of the animation playback, whether it plays forward (1) or in reverse (-1).
loop	This property allows you to control whether the player should loop the animation.

Supported read-only properties:

Property	Description
isReady	The player is ready.
isPlaying	The player is currently playing the animation.
states	The 'states' property provides a list of supported states by a processed icon.
frames	The 'frames' property provides the value of the animation length in terms of the number of frames.
duration	The 'duration' property provides the value of the animation length in seconds.

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