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.
Web
Install package
Install the package in your project.
npm install @lordicon/element
Set it up
Import and register the icon to make it available in your code.
import { defineElement } from "@lordicon/element";
// define "lord-icon" custom element with default properties
defineElement();
Use & Customize
Drop it into your HTML and adjust as you like!
Recommended usage
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.
API
Custom Element
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: |
|
colors |
Color palette in key-value format. Use color names from the icon's palette as keys. Example: |
|
stroke |
Line thickness for supported icons. Available values: |
|
speed |
Animation playback speed multiplier. Default is |
|
trigger |
Animation trigger type. Available: |
|
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: |
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>
Player
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: |
|
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.
Examples
Triggers
Discover all the built-in animation triggers available.
Trigger target
Utilize the 'target' attribute to specify the parent element responsible for triggering the animation.
Customization
Learn about all the customizable attributes supported by the element.
Current color
Delve into the 'current-color' class, allowing icons to inherit their color from a parent element.
CSS variables
Explore the use of CSS variables to customize colors.
Background
Discover how to use the element as a background.
Manual control
Gain insights into manual interaction with icons and players.
Icon loader
See an example of creating an icon loader callback, enabling you to provide icon data from alternative sources.
Loading (lazy)
Learn how to load icons only when needed.
Loading (lazy + effect)
Load icons only when needed and create a smooth, simultaneous fade-in effect after the load completes.
Loading (placeholder)
Display a small SVG placeholder until the custom element is ready.
Loading (placeholder + interaction)
Display a small SVG placeholder until the first user interaction with the element.
State
Explore the use of icon state animations.
Custom trigger
This example demonstrates how to create a straightforward custom animation trigger.
Custom trigger (scroll)
Create a custom trigger that plays an animation when a user scrolls the website.
Custom trigger (in screen)
Build an animation trigger that plays when the icon appears in the browser viewport.
Custom trigger (loop in screen)
Activate an already available 'loop' when the element appears fully on the user's screen.
Custom trigger (states)
This example demonstrates complex usage of states with a custom trigger. See how the trash icon appears, fills, and erases as the user interacts.
Upload
Get a preview of uploaded files.
Angular
Lordicon in pair with Angular.
Best practices
Minify
If you're not using multiple animations within a single icon in your project, consider using the 'minify' option when downloading its JSON. This will result in a smaller file that loads faster for users.
Optimizations
If you have the time and the technical skills, ensure that animated icons display 'instantly.' You can achieve this by:
- Downloading the SVG for a specific icon.
- Delaying the loading of the icon's JSON until the first interaction with it.
We have demonstrated how to achieve this in our examples and repository.
