dotLottie Web Player Basic Usage

This guide shows the simplest way to get a Lottie animation playing on your webpage using the core @lottiefiles/dotlottie-web player.

Prerequisites:

You have installed the player using one of the methods in the Installation Guide.
You have a Lottie animation file available (either a .json or .lottie file) via a URL or as local data.

Minimal Example (Using CDN)

This is the quickest way to see the player in action. Create an HTML file (e.g., index.html) with the following content:

<!DOCTYPE html>
<html>
  <head>
    <title>dotLottie Web Basic Example</title>
    <style>
      /* Optional: Add some basic styling */
      body {
        display: flex;
        justify-content: center;
        align-items: center;
        height: 100vh;
        margin: 0;
      }
      canvas {
        border: 1px solid lightgray;
      }
    </style>
  </head>
  <body>
    <!-- 1. The Canvas Element -->
    <canvas id="dotlottie-canvas" style="width: 300px; height: 300px;"></canvas>

    <!-- 2. The Script -->
    <script type="module">
      // Import the player from the CDN
      import { DotLottie } from "https://cdn.jsdelivr.net/npm/@lottiefiles/dotlottie-web/+esm";

      // Get a reference to the canvas
      const canvasElement = document.getElementById("dotlottie-canvas");

      // Create a new DotLottie instance
      new DotLottie({
        autoplay: true, // Play automatically
        loop: true, // Loop indefinitely
        canvas: canvasElement, // The canvas element to render on
        src: "https://lottie.host/4db68bbd-31f6-4cd8-84eb-189de081159a/IGmMCqhzpt.lottie", // Path/URL to your Lottie file
      });
    </script>
  </body>
</html>

To run this:

Save the code above as an HTML file (e.g., example.html).
Open the file directly in your web browser.

You should see the specified Lottie animation playing and looping inside the canvas element.

Core Concepts Explained

HTML Canvas (<canvas>): The dotLottie player renders the animation onto an HTML canvas element. You need to include this element in your HTML structure and give it an ID or select it in another way for the script.
Importing DotLottie: You need to import the DotLottie class, either from the installed package (import { DotLottie } from "@lottiefiles/dotlottie-web";) if using npm/yarn with a build tool, or directly from the CDN URL as shown in the example.
Instantiating DotLottie: You create a player instance using new DotLottie(options). The options object is crucial for configuration.
Essential Options:
- canvas: A reference to the <canvas> DOM element where the animation will be rendered.
- src: The URL to your animation file (.lottie or .json). Alternatively, you can use the data option to pass animation data directly (see Animation Loading).
- autoplay (boolean, default: false): Set to true to start playing immediately after loading.
- loop (boolean, default: false): Set to true to make the animation repeat indefinitely.

Controlling Playback Programmatically

While autoplay and loop handle common scenarios, you can control playback using methods on the DotLottie instance.

const dotLottie = new DotLottie({
  canvas: document.getElementById("dotlottie-canvas"),
  src: "path/to/your/animation.lottie",
  autoplay: false, // Start paused
});

// Wait for the animation to load before controlling it
dotLottie.addEventListener("load", () => {
  console.log("Animation Loaded!");

  // Example: Play after a button click
  document.getElementById("playButton").addEventListener("click", () => {
    dotLottie.play();
  });

  // Example: Pause after another button click
  document.getElementById("pauseButton").addEventListener("click", () => {
    dotLottie.pause();
  });
});

// Always handle potential loading errors
dotLottie.addEventListener("loadError", (err) => {
  console.error("Failed to load animation:", err);
});

Refer to the Playback Control guide for a full list of methods (play, pause, stop, setSpeed, setFrame, setSegment, etc.).

Cleaning Up

Remember to call dotLottie.destroy() when the animation is no longer needed to prevent memory leaks. See Best Practices.

Next Steps

Explore configuration options in the API Reference.
Learn about different ways of Loading Animations.
Customize appearance with Layout & Styling.
See more complex Examples.