React

In this guide, we will demonstrate how to use Lordicon icons within a React application. To streamline the entire process, we have prepared a player for you, making the integration significantly easier. The integration we present here is compatible with web and native environments (iOS, Android, Windows).

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.

Usage

To use the player, you must first install it:

npm install @lordicon/react

Next, in the code, we embed the Player component and obtain a handle to it, providing access to the API. For example:

import { useEffect, useRef } from 'react';
import { Player } from '@lordicon/react';

const ICON = require('./assets/lock.json');

export default function PlayOnce() {    
  const playerRef = useRef<Player>(null);
  
    useEffect(() => {
        playerRef.current?.playFromBeginning();
    }, [])

    return (
        <Player 
            ref={playerRef} 
            icon={ ICON }
        />
    );
}

Simple usage

Click to see a seamless integration of the player with a React app directly in your browser.

API

The <Player> supports the following parameters:

Name

Description

icon

Icon data.

size

Icon size.

state

Animation selection 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).

colorize

The ability to replace colors with specified values. For example: "#ff0000".

This method allows for an efficient color change without reloading the animation.

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".

Changing colors using this property significantly impacts animation loading performance; therefore, whenever possible, we recommend adjusting the icon using our editor. Changing colors in this way requires reloading the animation.

direction

Animation playback direction, either 1 or -1.

renderMode

Rendering method. For example: "AUTOMATIC", "HARDWARE", "SOFTWARE".

onReady

Callback triggered when the player is ready to work.

onComplete

Callback triggered after the animation has finished.

Available methods for the Player class:

Name

Description

play()

Play the animation.

playFromBeginning()

Play the animation from the beginning.

pause()

Pause the animation.

goToFirstFrame()

Go to the first animation frame.

goToLastFrame()

Go to the last animation frame.

Available read-only properties for the Player class:

Name

Description

frames

The 'frames' property provides the value of the animation length in terms of the number of frames.

isPlaying

The player is currently playing the animation.

states

The 'states' property provides a list of supported states by a processed icon.

currentState

Access to the current state.

Examples

Loop animation

An example with animation looped playback.

Show
Colorize

An example of how to change the colors of an animation to a single chosen color.

Show
Colors

An example of how to adjust specific icon colors during animation loading.

Show
Direction

Using animation direction to achieve interactive animations.

Show
States

Explore the use of icon state animations.

Show
React

Using Lordicon with React (without using react-native).

Show
CSS Variables

Usage of CSS variables with the Lordicon React library. Available only in web environments.

Show

Best practices

Icon hosting

While we expect minimal issues, there is no guarantee of 100% CDN uptime. If your project is of paramount importance to your clients, we suggest you consider hosting icons as Lottie JSON (Lordicon) on your own.

Minify

If you're not using multiple animations or strokes 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.