Lottie animation integration

Learn how to integrate Lottie animations with Helios for deterministic playback control

Lottie animations can be synchronized with Helios by loading them with autoplay disabled and manually seeking to specific time positions based on Helios frame updates.

Installation

Install Lottie Web alongside Helios:

npm install lottie-web @helios-project/core

Basic integration

The integration involves:

1. Loading a Lottie animation with autoplay: false and loop: false
2. Subscribing to Helios updates
3. Converting frame numbers to milliseconds
4. Seeking the Lottie animation to the exact time

import { Helios } from '@helios-project/core';
import lottie from 'lottie-web';
import animationData from './animation.json';

const helios = new Helios({
  duration: 2, // 60 frames @ 30fps = 2s
  fps: 30,
});

const container = document.getElementById('lottie-container');

if (container) {
    const anim = lottie.loadAnimation({
      container,
      renderer: 'svg',
      loop: false,
      autoplay: false,
      animationData: animationData,
    });

    helios.subscribe(({ currentFrame, fps }) => {
      // Convert frame to milliseconds
      const timeMs = (currentFrame / fps) * 1000;
      // Seek Lottie (isFrame = false means time in ms)
      anim.goToAndStop(timeMs, false);
    });
}

Integration pattern

Load animation without autoplay

Disable automatic playback so Helios can control the animation:

const anim = lottie.loadAnimation({
  container: element,
  renderer: 'svg', // or 'canvas', 'html'
  loop: false,
  autoplay: false,
  animationData: animationData,
});

Frame to time conversion

Convert Helios frame numbers to milliseconds:

const timeMs = (currentFrame / fps) * 1000;

Seek to exact position

Use goToAndStop with time in milliseconds:

// Second parameter false means first parameter is time (ms)
anim.goToAndStop(timeMs, false);

// If you want to use frame numbers instead:
// anim.goToAndStop(frameNumber, true);

Renderer options

Lottie supports multiple renderers:

SVG renderer

renderer: 'svg'

Best for:

• Scalable vector graphics
• High quality at any resolution
• Complex paths and shapes

Canvas renderer

renderer: 'canvas'

Best for:

• Better performance with many elements
• Raster effects
• Particle systems

HTML renderer

renderer: 'html'

Best for:

• DOM-based animations
• Text animations
• CSS filter effects

HTML structure

Provide a container element for the Lottie animation:

<div id="lottie-container" style="width: 400px; height: 400px;"></div>

Why this works

By disabling autoplay and manually seeking the Lottie animation, Helios can:

• Ensure deterministic frame-by-frame rendering
• Enable scrubbing through the animation
• Support export to video formats
• Maintain synchronization with other animated elements

This pattern works with any Lottie animation exported from After Effects or other tools that support the Lottie format.