> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BintzGavin/helios/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
const timeMs = (currentFrame / fps) * 1000;
```

### Seek to exact position

Use `goToAndStop` with time in milliseconds:

```typescript theme={null}
// 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

```typescript theme={null}
renderer: 'svg'
```

Best for:

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

### Canvas renderer

```typescript theme={null}
renderer: 'canvas'
```

Best for:

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

### HTML renderer

```typescript theme={null}
renderer: 'html'
```

Best for:

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

## HTML structure

Provide a container element for the Lottie animation:

```html theme={null}
<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.