Skip to main content
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: 
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
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: 
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: 
const timeInSeconds = state.currentFrame / state.fps;
tl.seek(timeInSeconds);

​
Using GSAP easing

GSAP provides powerful easing functions that work seamlessly: 
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us