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.