GSAP Animations with Visual Radio Graphics

To add GSAP animations to your Visuals in Visual Radio Assist, you can make use of the custom JS in the Designer.

Quick Start

Hello World Animation

Fade in a text layer when the visual appears:

if (typeof visualLink !== "undefined") {
  const pm = visualLink.playStateManager;
  const getCanvasElement = visualLink.getCanvasElement;

  pm.on("enter", () => {
    gsap.to(getCanvasElement("my-text-layer"), {
      opacity: 1,
      duration: 1
    });
  });
}

Required Steps:

Add custom JS to your visual
Set layer ID to my-text-layer (bottom of layer properties)
Turn off default transition on that layer

Core Concepts

The visualLink Object

visualLink connects your JavaScript to the visual lifecycle. Always check it exists:

if (typeof visualLink !== "undefined") {
  // Your code here
}

When writing custom JavaScript for visuals, you have access to the visualLink object that provides methods to interact with your visual canvas. It’s the link between the code and the visual lifecycle and data. Every layer is accessible via the visualLink.

Getting Elements

Never use document.querySelector - visuals renderer places elements in different contexts on the page, there is no guarantee that the querySelector will query the element you expect it to return.

// NEVER use class names or IDs directly in custom JS
gsap.to("#title-ed8732d"...
gsap.to(".list item"...

document.querySelector("#title-ede8w9")...

Always use visualLink.getCanvasElement():

// By ID
const title = visualLink.getCanvasElement("title-layer");

// By class (returns multiple)
const items = visualLink.getCanvasElement(".list-item");

Set IDs at bottom of layer properties panel.

The Play State Manager

visualLink.playStateManager controls when your visual appears and disappears. It fires events at key moments in the visual’s lifecycle.

const pm = visualLink.playStateManager;  // Shorthand for convenience

You register handlers for these moments using pm.on().

Lifecycle Events

Visuals have 3 key moments:

const pm = visualLink.playStateManager;

// 1. Before showing (prepare state)
pm.on("cuein", () => {
  // Reset animations to start position
});

// 2. Show visual (play in animation)
pm.on("enter", () => {
  // Start your animation
});

// 3. Hide visual (play out animation)
pm.on("leave", () => {
  // Exit animation
});

Execution order: cuein → enter → leave

GSAP Basics

Three Animation Methods

// Animate TO a state
gsap.to(".element", { x: 100, duration: 1 });

// Animate FROM a state to current
gsap.from(".element", { opacity: 0, duration: 1 });

// Define both start and end
gsap.fromTo(".element",
  { opacity: 0, y: 50 },
  { opacity: 1, y: 0, duration: 1 }
);

Common Properties

{
  // Position
  100,            // Move right 100px
  y: -50,            // Move up 50px

  // Appearance
  opacity: 0.5,      // Fade to 50%
  scale: 1.2,        // Scale to 120%
  rotation: 45,      // Rotate 45deg

  // Timing
  duration: 1,       // 1 second
  delay: 0.5,        // Wait 0.5s before start
  ease: "power2.out" // Easing function
}

GSAP Cheatsheet

Complete Examples

Example 1: Simple Fade In

if (typeof visualLink !== "undefined") {
  const pm = visualLink.playStateManager;
  const getCanvasElement = visualLink.getCanvasElement;

  const title = getCanvasElement("title");

  pm.on("enter", () => {
    gsap.from(title, {
      opacity: 0,
      duration: 0.5
    });
  });
}

What this does: Title fades in over 0.5s when visual enters.

Example 2: Slide In + Fade Out

if (typeof visualLink !== "undefined") {
  const pm = visualLink.playStateManager;
  const getCanvasElement = visualLink.getCanvasElement;

  const subtitle = getCanvasElement("subtitle");

  pm.on("enter", () => {
    gsap.from(subtitle, {
      x: -100,
      opacity: 0,
      duration: 0.6
    });
  });

  pm.on("leave", () => {
    gsap.to(subtitle, {
      opacity: 0,
      duration: 0.3
    });
  });
}

What this does:

Enter: Slides in from left with fade
Leave: Fades out

Example 3: Multiple Layers

if (typeof visualLink !== "undefined") {
  const pm = visualLink.playStateManager;
  const getCanvasElement = visualLink.getCanvasElement;

  const layers = [
    getCanvasElement("layer-1"),
    getCanvasElement("layer-2"),
    getCanvasElement("layer-3")
  ];

  pm.on("enter", () => {
    gsap.from(layers, {
      opacity: 0,
      y: 30,
      duration: 0.5,
      stagger: 0.2  // 0.2s delay between each
    });
  });
}

What this does: 3 layers appear one after another with 0.2s delay.

Example 4: Using Timelines

For complex multi-step animations:

if (typeof visualLink !== "undefined") {
  const pm = visualLink.playStateManager;
  const getCanvasElement = visualLink.getCanvasElement;

  const title = getCanvasElement("title");
  const subtitle = getCanvasElement("subtitle");
  const logo = getCanvasElement("logo");

  const timeline = gsap.timeline({ paused: true });

  timeline
    .from(logo, { scale: 0, duration: 0.4 })
    .from(title, { opacity: 0, y: -20, duration: 0.3 }, "-=0.2")
    .from(subtitle, { opacity: 0, duration: 0.3 });

  pm.on("enter", () => {
    timeline.restart();
  });
}

What this does:

Logo scales up
Title fades in from top (slightly before logo finishes)
Subtitle fades in

Example 5: Full In/Out with Reset

if (typeof visualLink !== "undefined") {
  const pm = visualLink.playStateManager;
  const getCanvasElement = visualLink.getCanvasElement;

  const layer = getCanvasElement("animated-layer");

  const intro = gsap.timeline({ paused: true });
  const outro = gsap.timeline({ paused: true });

  intro.fromTo(layer,
    { opacity: 0, x: -50 },
    { opacity: 1, x: 0, duration: 0.6 }
  );

  outro.to(layer, {
    opacity: 0,
    x: 50,
    duration: 0.4
  });

  pm.on("cuein", () => {
    intro.progress(0).pause();
    outro.progress(0).pause();
  });

  pm.on("enter", () => {
    if (!intro.isActive()) intro.restart();
  });

  pm.on("leave", () => {
    if (!outro.isActive()) outro.restart();
  });
}

What this does:

cuein: Reset both animations
enter: Slide in from left
leave: Slide out to right

Important: Always reset animations in cuein to prevent state issues.

Transition Settings

Found in Visual settings below tag editor. Controls overall visual transition behavior.

Default

Layers transition independently. Each layer uses its own timing. Use when: Simple visuals with independent layer animations.

Layer Based

Visual waits for ALL layers to finish transitioning. Duration = sum of all layer transitions Use when: Coordinated multi-layer animations where all must complete.

Visual Based

Fixed duration for entire visual, layers animate within that time. Settings:

In Duration (ms): Time to show visual
Out Duration (ms): Time to hide visual

Use when: Consistent timing regardless of layer complexity.

Visual Fixed

Single fixed-length visual. No individual layer control. Settings:

In Duration (ms): Show time
Out Duration (ms): Hide time
Layer transitions disabled

Use when: Simple displays, no complex timing needed.

Common Patterns

Pattern: Layer That Only Animates In

pm.on("enter", () => {
  gsap.from(layer, { opacity: 0, duration: 0.5 });
});
// No leave handler - uses default out

Pattern: Continuous Animation

pm.on("enter", () => {
  gsap.to(layer, {
    rotation: 360,
    duration: 2,
    repeat: -1,      // Infinite
    ease: "none"     // Linear
  });
});

Pattern: Sequence Multiple Animations

const tl = gsap.timeline();

tl.to(layer1, { opacity: 1, duration: 0.3 })
  .to(layer2, { x: 100, duration: 0.5 })
  .to(layer3, { scale: 1.5, duration: 0.4 });

Pattern: Overlap Animations

const tl = gsap.timeline();

tl.to(layer1, { opacity: 1, duration: 0.5 })
  .to(layer2, { x: 100, duration: 0.5 }, "-=0.3")  // Start 0.3s before layer1 ends
  .to(layer3, { scale: 1.5, duration: 0.5 }, "+=0.2");  // Start 0.2s after layer2 ends

Troubleshooting

Animation doesn’t run

typeof visualLink !== "undefined" wrapper exists
Layer ID matches getCanvasElement("id")
Default transition disabled on animated layers
Console for errors

Animation runs but looks wrong

Using lifecycle events correctly (cuein/enter/leave)
Reset animations in cuein for repeatable playback
Transition Settings mode matches intent

Element not found

Layer ID set in properties (bottom of panel)
Using visualLink.getCanvasElement() not document.querySelector
ID has no # prefix in getCanvasElement("id")

Animation plays multiple times

Solution: Check if active before restarting:

pm.on("enter", () => {
  if (!timeline.isActive()) {
    timeline.restart();
  }
});

Visual data not updating

Access visual data via visualLink.data:

console.log(visualLink.data);  // See all available properties
const artistName = visualLink.data.artist;

Best Practices

Always check visualLink exists before any code
Always use visualLink.getCanvasElement() for DOM queries
Reset animations in cuein for reliable repeated playback
Disable default transitions on GSAP-animated layers
Use timelines for multi-step animations
Check isActive() before restarting animations
Keep durations under 1s for snappy UI
Test with repeated plays (cuein → enter → leave)

Reference

visualLink API

visualLink.data                     // Visual content data
visualLink.canvas()                 // Main canvas element
visualLink.getCanvasElement(query)  // Query elements safely
visualLink.playStateManager         // Lifecycle events
visualLink.abortController          // Cleanup controller

Lifecycle Events

pm.on("cuein", handler)   // Before show (reset)
pm.on("enter", handler)   // Show visual (in animation)
pm.on("leave", handler)   // Hide visual (out animation)

GSAP Essentials

gsap.to(target, vars)
gsap.from(target, vars)
gsap.fromTo(target, fromVars, toVars)
gsap.timeline(vars)

Full GSAP Docs GSAP Cheatsheet

Layer Transition Lifecycle for CSS

Core Control API

​Quick Start

​Hello World Animation

​Core Concepts

​The visualLink Object

​Getting Elements

​The Play State Manager

​Lifecycle Events

​GSAP Basics

​Three Animation Methods

​Common Properties

​Complete Examples

​Example 1: Simple Fade In

​Example 2: Slide In + Fade Out

​Example 3: Multiple Layers

​Example 4: Using Timelines

​Example 5: Full In/Out with Reset

​Transition Settings

​Default

​Layer Based

​Visual Based

​Visual Fixed

​Common Patterns

​Pattern: Layer That Only Animates In

​Pattern: Continuous Animation

​Pattern: Sequence Multiple Animations

​Pattern: Overlap Animations

​Troubleshooting

​Animation doesn’t run

​Animation runs but looks wrong

​Element not found

​Animation plays multiple times

​Visual data not updating

​Best Practices

​Reference

​visualLink API

​Lifecycle Events

​GSAP Essentials

Quick Start

Hello World Animation

Core Concepts

The visualLink Object

Getting Elements

The Play State Manager

Lifecycle Events

GSAP Basics

Three Animation Methods

Common Properties

Complete Examples

Example 1: Simple Fade In

Example 2: Slide In + Fade Out

Example 3: Multiple Layers

Example 4: Using Timelines

Example 5: Full In/Out with Reset

Transition Settings

Default

Layer Based

Visual Based

Visual Fixed

Common Patterns

Pattern: Layer That Only Animates In

Pattern: Continuous Animation

Pattern: Sequence Multiple Animations

Pattern: Overlap Animations

Troubleshooting

Animation doesn’t run

Animation runs but looks wrong

Element not found

Animation plays multiple times

Visual data not updating

Best Practices

Reference

visualLink API

Lifecycle Events

GSAP Essentials