How to add Lottie to React

Choose one player deliberately

Start with the format your animator will deliver and the features it uses. Confirm that the selected runtime supports them, then choose a React integration that fits your application. Avoid loading two different players for the same visual unless there is a specific, tested reason. Runtime duplication adds work and can make ownership of playback behavior confusing.

Record the package and version in the project. When a dependency is upgraded, run the same representative animation checks again. A file that worked with one renderer is not evidence that every renderer or future version will behave identically.

Add a stable component boundary

Install the selected package through the project’s normal dependency workflow. With dotLottie React, the component accepts an animation source and playback options. Start with autoplay disabled so you can verify the asset, dimensions and visual result before adding behavior. Use a local, stable path or an intentionally managed hosting location.

Give the component explicit dimensions or an aspect ratio. That prevents the page from waiting for the animation to determine its layout. In responsive interfaces, decide how the artwork should fit inside the available space: preserving the full composition and cropping it are different design choices.

Connect the animation to product state

A success sequence should be triggered by a real successful operation, not by the start of a request. Loading motion should stop when loading stops, and an error should lead to an intentional visual state. Write down these transitions before connecting the player to your component logic. This keeps the motion model aligned with the product.

Decide what happens when a request is cancelled, the user navigates away or another action interrupts the sequence. A happy-path demo does not cover those cases. Keep essential status messages in accessible HTML so the animation is not the only way to understand what happened.

Manage lifecycle and visibility

Use the player reference and documented controls to start, pause or move to a frame. Add visibility handling so a player is not continually rendering below the viewport or in a background tab. If your runtime supports freezing, understand the difference between that behavior and pausing the timeline before choosing it.

Clean up observers and event listeners when the component unmounts. Development environments may intentionally repeat lifecycle work to reveal problems, so an integration should not depend on an effect running exactly once. Keep references to the current player and avoid callbacks that act on an instance after it has been replaced.

Handle accessibility and failure

Determine whether the motion is decorative or meaningful. Decorative visuals should not add repetitive noise for assistive technology. Meaningful visuals need a text alternative or an equivalent status message. Provide a reduced-motion experience that still communicates the important result, and let a user deliberately play motion when appropriate.

Design the loading and error states. A static poster can preserve context while the player initializes. If the asset fails to load, show a useful fallback instead of an indefinite spinner. Retrying, opening a reference or continuing the product workflow may all be appropriate depending on the animation’s role.

Test the production build

Check the published application, not just the local component preview. Build configuration, asset paths, content policies and deployment directories can change how files are loaded. Inspect browser requests and console errors, then test a cold page load and navigation back to the component. Confirm that the animation does not keep running after it is no longer relevant.

Measure on a representative phone with the surrounding product visible. A gallery of several players behaves differently from one isolated test. If the integration is expensive, review the artwork, player choice and simultaneous instance count before trying to fix the problem with a higher-performance device.

Review the component as a product feature

A useful component contract includes a source, an accessible description when needed, a playback state and an error outcome. Keep product events outside the animation data where possible. For example, the component can receive a confirmed success state from the application rather than infer success from elapsed animation time. That separation makes both the interface and the motion easier to test.

Think through rapid state changes. A user may submit twice, cancel a request, switch tabs or navigate before a sequence finishes. Decide whether the next state interrupts, resets or waits for the current animation. Test those transitions explicitly instead of assuming the complete event always arrives. The player should never prevent the rest of the product from recovering from an error.

For server-rendered applications, confirm how the selected package handles browser-only APIs and hydration. Follow the framework and runtime documentation rather than assuming every package can execute on the server. Keep the reserved layout and text fallback available before interactive code loads. A user should be able to understand the screen while the animation code is still arriving.

During review, inspect repeated mounting and unmounting, changing the source, and returning to the same route. Watch for duplicate instances, orphaned listeners and callbacks from an old player. These issues can be invisible in a one-time screenshot. A good handoff includes the tested package version and a small integration example that demonstrates the intended state transitions, not just an asset URL.

A format decision table

A practical handoff checklist

Before approving delivery, open the animation inside the intended screen with real content. Compare it with the agreed reference and check the start, loop boundary and final state. Confirm that the animation does not cover a control, obscure a label or leave the user waiting for decoration to finish. Review it at the smallest supported layout as well as the desktop presentation.

Ask for the agreed delivery files, a reference preview, the tested player and version, and a note describing triggers and fallback behavior. Confirm source-file and usage-rights arrangements in the project scope. A developer should not need to guess whether an animation loops, which frame is the resting state, or whether an embedded image is intentionally part of the file.

Test slow loading, an unavailable asset, reduced motion and navigation away from the screen. Keep essential instructions and status in accessible HTML. If a sequence is purely decorative, its failure should not block the task. If it helps explain a process, provide an equivalent explanation that remains available without playback.

Finally, assign an owner for future changes. Product copy, design systems and runtime dependencies evolve. Keep the approved source and integration notes together so a later update can be checked against the original intent. This small amount of documentation makes a custom animation easier to maintain beyond the launch.

Frequently asked questions