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

# GSAP integration

> Learn how to integrate GSAP animations with Helios for deterministic timeline control

GSAP is a powerful animation library that can be synchronized with Helios by pausing its timeline and seeking to specific time positions based on Helios frame updates.

## Installation

Install GSAP alongside Helios:

```bash theme={null}
npm install gsap @helios-project/core
```

## Basic integration

The key to integrating GSAP with Helios is to:

1. Create a GSAP timeline with `paused: true`
2. Subscribe to Helios updates
3. Convert frame count to seconds
4. Seek the GSAP timeline to the exact time

```typescript theme={null}
import { Helios } from "@helios-project/core";
import { gsap } from "gsap";

// 1. Initialize Helios
const helios = new Helios({
  fps: 30,
  duration: 5,
});

// 2. Setup GSAP Timeline
// IMPORTANT: The timeline must be paused so Helios can drive it!
const tl = gsap.timeline({ paused: true });

// 3. Define animations
tl.to(".box", {
  rotation: 360,
  x: 100,
  duration: 2,
  ease: "power1.inOut"
})
.to(".box", {
  scale: 2,
  backgroundColor: "#00eeff",
  duration: 2,
  ease: "elastic.out(1, 0.3)"
})
.to(".box", {
  x: 0,
  scale: 1,
  duration: 1,
  ease: "power2.out"
});

// 4. Subscribe to Helios updates to drive GSAP
helios.subscribe((state) => {
  // Convert frame count to seconds
  const timeInSeconds = state.currentFrame / state.fps;

  // Seek the GSAP timeline to the exact time
  tl.seek(timeInSeconds);
});

// 5. Start Helios (bind to document timeline for preview)
helios.bindToDocumentTimeline();
```

## Integration pattern

### Timeline control

GSAP timelines must be created with `paused: true` to prevent automatic playback:

```typescript theme={null}
const tl = gsap.timeline({ paused: true });
```

This allows Helios to have full control over the timeline position.

### Frame to time conversion

Convert Helios frame numbers to seconds for GSAP:

```typescript theme={null}
const timeInSeconds = state.currentFrame / state.fps;
tl.seek(timeInSeconds);
```

### Using GSAP easing

GSAP provides powerful easing functions that work seamlessly:

```typescript theme={null}
tl.to(".element", {
  x: 100,
  duration: 2,
  ease: "elastic.out(1, 0.3)"
});
```

Common easing options:

* `power1.inOut`, `power2.out`, `power3.in`
* `elastic.out(1, 0.3)`
* `bounce.out`
* `back.inOut(1.7)`

## Why this works

By pausing the GSAP timeline and manually seeking to specific time positions, Helios can:

* Ensure deterministic frame-by-frame rendering
* Enable scrubbing through the animation
* Support export to video formats
* Maintain synchronization across multiple animation systems

This pattern works with any GSAP feature including plugins, custom properties, and complex timelines.