Dotlottie `canvas` element aspect ratio out of sync with scene's aspect ratio

[mseeley]

Overview

Similar to #248

There is an implicit gap rendering above and below our rectangular animations. This prevents our developers from deterministically spacing an animation from the content before and after it. I understand there is animation scaling occurring yet the math results in a canvas element with an aspect ratio out of sync with the scene.

• Rectangle lottie and json.zip
• Codesandbox.

This 700x300 scene:

Displays like this; see Codesandbox.

The 700x300 (2.33 aspect-ratio) scene results in a 700x349.72 (2.0 aspect-ratio) canvas rectangle.

Consuming repo

What repo were you working in when this issue occurred?

I have run into the same behavior when using @lottiefiles/dotlottie-vue in local development and when using dotlottie-wc syntax directly from app.lottiefiles.com

...

Labels

• Add the Type: Bug label to this issue.

[mseeley]

Hello maintainers, is there anything I can do to help clarify the issue?

[theashraf]

Hi @mseeley, by design, the dotLottie player scales the animation to fit within the canvas element’s existing dimensions. If the canvas has a default aspect ratio that doesn’t match the animation’s original ratio, you’ll see extra space (often above or below the animation). Essentially, the animation is being “contained” within the canvas.

To avoid the mismatch, you can force the canvas to match the animation’s intended ratio. For example:

import { DotLottie } from "https://esm.sh/@lottiefiles/dotlottie-web";

const canvas = document.getElementById("dotLottie-canvas");

const dotLottie = new DotLottie({
  canvas,
  src: "YOUR_RECTANGLE_ANIMATION.lottie",
  loop: true,
  autoplay: true
});

dotLottie.addEventListener("load", () => {
  // 1) Get the original animation size (e.g. 700×300)
  const { width: animWidth, height: animHeight } = dotLottie.animationSize();

  // 2) Calculate aspect ratio
  const aspectRatio = animWidth / animHeight;

  // 3) Read current canvas width from CSS
  const canvasWidth = canvas.getBoundingClientRect().width;

  // 4) Enforce the correct height based on aspect ratio
  const newHeight = canvasWidth / aspectRatio;
  canvas.style.height = `${newHeight}px`;

  // 5) Let dotLottie know you’ve changed dimensions
  dotLottie.resize();
});

With this setup, the canvas will match the animation’s exact aspect ratio, eliminating any extra gaps and preventing the auto-fit scaling from distorting or padding your animation.

Codepen example for reference https://codepen.io/lottiefiles/pen/WbNxKbv

[mseeley]

Hi @theashraf thank you for the explanation and code sample, too. :)

If the dotLottie player was fitting the animation into an canvas element which it didn't control then the contain behavior makes a lot of sense.

But, with the dotLottie player knowing the animation aspect ratio and owning the canvas element, then isn't it most intuitive for the canvas element to be created to match the animation's intrinsic aspect ratio? Is there a technical reason or design goal which makes the desynced aspect ratios necessary?

Thanks!

---

Edit: Ah, I see now. In your code sample dotLottie doesn't own the canvas element. I'm thinking about this from the standpoint of a consumer of the web component and Vue wrapper where the canvas element is owned by the wrapper.

I still suggest it's most intuitive that those wrappers handle canvas aspect ratio automatically or through an aspect-ratio prop. Does this sound reasonable? If so, would you suggest I follow-up in those repos?

Thank you very much for your input. 🙇

[theashraf]

@mseeley Your suggestion makes sense. Introducing a maintainAspectRatio (or similar) prop that internally controls styles could resolve this issue. but, my main concern is that user defined canvas styles won't apply when this prop is used.

and since this isn't a common scenario, I'll keep the issue open for additional feedback. Typically, users want their animations to fit within a specific area on the page, rather than adjusting the layout around the animation itself.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs.

[gjrogala]

This is really annoying as the previous and didn't force any aspect ratio of the animation.

I have a bunch of specific aspect-ratio Lottie animations (usually 1:1) that I designed to fit specific containers and now I end up with a lot of white space on the sides which makes the animation appear smaller.

I guess that because the uses canvas there is no easier fix except for the suggested JS approach which isn't really a solution for me.