How to add Lottie to WordPress

Identify your WordPress environment

WordPress sites vary in their editor, theme, plugins and hosting restrictions. A tutorial that works in one setup may depend on permissions or a page builder that another site does not have. Record the editor you use, whether custom scripts are allowed and how assets are normally managed before choosing an integration method.

Make changes in a staging environment and preserve the working version of the page. The goal is a maintainable animation component, not a one-off snippet that only one administrator understands. If a developer maintains the site, involve them before adding another runtime.

Choose one integration owner

A suitable block or plugin can provide an editor-friendly workflow, while a theme or custom plugin can provide more deliberate control. Evaluate compatibility, maintenance and the features you need. Do not install several animation plugins simply to test similar capabilities on a live page; duplicated players and conflicting settings make problems harder to diagnose.

Use the site’s normal process for loading scripts and styles. Keep the player dependency separate from content editors’ routine copy changes when possible. That helps avoid accidentally removing the runtime or loading it multiple times across repeated blocks.

Understand Custom HTML permissions

The Custom HTML block is useful for markup, but permission to preserve scripts and embeds is not universal. WordPress can sanitize disallowed markup when content is saved. If a script disappears, investigate the role and site configuration instead of repeatedly pasting it or trying to defeat the site’s protections.

A developer-managed integration can provide the required behavior without asking editors to handle executable code. Hosting policies and security plugins may also affect asset types or remote requests. Confirm what the site supports before deciding that a particular animation file is broken.

Prepare the asset and component

Use a real Lottie export intended for the selected player. Keep the asset URL stable and verify any linked images or fonts. Give the visual a predictable width, height or aspect ratio so the page does not shift when it appears. A poster is useful while the player initializes and as a fallback when motion is unavailable.

Consider responsive composition. A detailed dashboard illustration that looks clear on a desktop may be unreadable in a narrow content column. Share the actual block dimensions with the animator, including the mobile layout, rather than relying on a generic export size.

Test with caching and optimization enabled

WordPress sites often combine caching, script optimization and content-delivery tools. Test the published staging page with the same configuration used in production. Check a fresh visit, a cached visit and navigation back to the page. If an optimization changes script order, the integration should still initialize predictably.

When something fails, separate the asset request, runtime loading, layout and playback trigger. Browser errors can show whether the file is missing or the player is unavailable. Changing unrelated settings at the same time makes it difficult to know which change resolved the problem.

Keep the result accessible and maintainable

Offer a reduced-motion experience, stop nonessential playback outside the viewport and provide text for meaningful states. A motion component should not prevent keyboard navigation or make a form harder to use. Test it with the surrounding theme and the real page content, because those conditions are part of the delivered experience.

Document how to replace the animation, which settings control playback and how to restore the poster. Keep the original approved reference and the player version. When commissioning a new asset, include the WordPress environment and any plugin constraints in the brief so the animation is designed for a realistic implementation.

Choose a maintainable integration

First identify who maintains the WordPress site and which editing workflow they use. A block-based site, a page-builder project and a custom theme can require different integration approaches. Prefer an established workflow that the owner can update safely. The animation should not depend on a hidden snippet that only one developer knows how to find.

If a plugin supplies the player, check its current support, configuration and compatibility with the site. If the theme owns the integration, load the script through the project’s normal asset system. Avoid inserting the same player separately in several blocks. A page containing multiple animations can share the runtime while each instance manages its own playback and lifecycle.

Test with the site’s actual caching and optimization settings enabled. Script deferral, content policies, asset rewriting and a content delivery network can affect initialization or paths. Clear only the relevant caches through the normal maintenance process, then verify the published result. Do not disable security controls or grant broad permissions just to make an embedded script run.

Give the editor a short replacement checklist: upload the compatible asset, retain the expected layout, preview the page, check mobile and confirm the fallback. Include any required poster and accessible text. If the animation communicates a product state, identify the application event that controls it. A decorative page-builder loop and a stateful application interaction should not be treated as the same integration task.

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