Getting Started with the dotLottie Web Component Player

In this tutorial, you will install and configure the <dotlottie-player> web component to display your first Lottie animation in an HTML page or JavaScript project.

Prerequisites

Basic understanding of HTML and JavaScript.
Access to the @lottiefiles/dotlottie-web package, either via npm/yarn or CDN.

Setup

To use the <dotlottie-player> custom element, you first need to load its definition.

Method 1: Using a Script Tag (CDN)

This is the simplest method for plain HTML pages. Include this script tag, preferably in the <head> or before your closing </body> tag.

<!-- Load from CDN -->
<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@lottiefiles/dotlottie-web@latest/dist/dotlottie-web.js"
></script>

Method 2: Importing in JavaScript (Build Tools)

If you're using a build tool like Vite, Webpack, or Parcel and have installed the package (npm install @lottiefiles/dotlottie-web), import it for its side effects in your main JavaScript/TypeScript file:

// Import the side effect to register the <dotlottie-player> element
import "@lottiefiles/dotlottie-web";

// Your application code...

Basic Usage

Once the component is registered (via script or import), you can use the <dotlottie-player> tag directly in your HTML:

<!DOCTYPE html>
<html>
  <head>
    <title>dotLottie Web Component Example</title>
    <!-- Load the component definition -->
    <script type="module" src="..."></script>
    <!-- Or rely on JS import -->
    <style>
      dotlottie-player {
        display: block; /* Recommended for sizing */
        width: 300px;
        height: 300px;
        margin: 20px auto;
      }
    </style>
  </head>
  <body>
    <h1>My Animation</h1>

    <dotlottie-player
      src="https://lottie.host/YOUR_ANIMATION_URL.lottie"
      autoplay
      loop
    >
    </dotlottie-player>
  </body>
</html>

Key Attributes:

src: (Required) The URL to your .lottie or .json animation file.
autoplay: Add this attribute to make the animation play automatically on load.
loop: Add this attribute to make the animation loop continuously.

Styling

The <dotlottie-player> element can be styled using standard CSS like any other HTML element:

dotlottie-player {
  width: 100%;
  max-width: 500px;
  height: auto;
  aspect-ratio: 16 / 9; /* Example aspect ratio */
  border-radius: 8px;
}

Automatic Cleanup

The web component handles the cleanup of the internal animation instance automatically when the element is removed from the DOM.

Next Steps

Configure: See all available options in the Attributes Reference.
Control & Interact: Learn how to use JavaScript to control playback and listen to events in the Examples.