Frontend Animation Implementation

This document explains how the GSAP animation controls work on the frontend to execute animations based on the block editor configuration.

📚 For complete user documentation, see Animation Controls

Overview

The frontend implementation consists of three main components:

PHP Render Filter – Injects animation data attributes into block HTML
JavaScript Animation Controller – Executes animations based on data attributes
CSS Styles – Provides styling and performance optimizations

How It Works

1. Block Rendering (PHP)

When blocks are rendered on the frontend, the add_animation_attributes() method in Blocks.php processes each block:

Checks if the block type supports animations
Reads animation configuration from block attributes
Injects data attributes into the block's HTML

Example Output:

<div class="wp-block-group" 
     data-animation-enabled="true"
     data-animation-type="slideInUp" 
     data-animation-trigger="inView"
     data-animation-duration="1"
     data-animation-delay="0.5"
     data-animation-ease="power2.out">
  <!-- Block content -->
</div>

2. Script Enqueuing (PHP)

The enqueue_animation_assets() method:

Scans page content for animated blocks
Only loads animation assets when needed (performance optimization)
Enqueues both JavaScript and CSS
Passes configuration data to frontend script

3. Animation Execution (JavaScript)

The frontend script (frontend.js) handles animation execution:

Initialization Process

Waits for GSAP library to be available
Registers ScrollTrigger plugin if needed
Finds all elements with data-animation-enabled="true"
Initializes animations for each element

Animation Types

In-View Animations:

Uses Intersection Observer API for trigger detection
Plays animation when element enters viewport
Supports stagger for child elements

Scroll-Based Animations:

Uses GSAP ScrollTrigger plugin
Links animation progress to scroll position
Supports scrubbing, pinning, and snapping

Animation Presets

The frontend includes these preset animations:

fadeIn – Simple opacity transition
slideInUp/Down/Left/Right – Movement with opacity
scaleIn – Scale and opacity transition
rotateIn – Rotation with opacity
custom – User-defined transform values

4. Performance Optimizations

CSS Optimizations:

GPU acceleration with will-change property
backface-visibility: hidden for better rendering
Visibility control to prevent content flash

JavaScript Optimizations:

Lazy loading – only initialize when GSAP is available
Intersection Observer for efficient viewport detection
Single ScrollTrigger refresh after all animations setup

Accessibility:

Respects prefers-reduced-motion media query
Disables animations for users who prefer reduced motion
Print-friendly styles disable animations in print

Data Attributes Reference

Core Animation Attributes

data-animation-enabled – "true" when animation is active
data-animation-type – Animation preset or "custom"
data-animation-trigger – "inView" or "scroll"
data-animation-duration – Duration in seconds
data-animation-delay – Delay before animation starts
data-animation-ease – GSAP easing function
data-animation-stagger – Stagger delay for child elements

ScrollTrigger Attributes

data-scroll-trigger-start – Start position (e.g., "top 80%")
data-scroll-trigger-end – End position (e.g., "bottom 20%")
data-scroll-trigger-scrub – "true" for scrub animation
data-scroll-trigger-scrub-value – Scrub smoothness (0.1-5)
data-scroll-trigger-pin – "true" to pin element
data-scroll-trigger-snap-type – Scroll snap behavior
data-scroll-trigger-refresh – "true" for auto refresh

Custom Transform Attributes (when type="custom")

data-animation-from-x/y/scale/rotation/opacity – Initial values
data-animation-to-x/y/scale/rotation/opacity – Target values

Dependencies

Required

GSAP 3.x library loaded on the page
Modern browser with Intersection Observer support

Optional

GSAP ScrollTrigger plugin (for scroll-based animations)
GSAP other plugins based on animation requirements

Browser Support

The frontend code supports:

Modern browsers with ES6+ support
Intersection Observer API (built-in polyfill detection)
CSS Grid and Flexbox
CSS Custom Properties

Legacy browser support can be added with appropriate polyfills.

Debugging

Development Mode

When WP_DEBUG is enabled, additional configuration is passed to the frontend:

window.linchpinAnimationConfig = {
  debug: true,
  reducedMotion: false
};

Console Warnings

The script will log warnings for:

Missing GSAP library
Missing ScrollTrigger plugin (when needed)
Animation initialization errors

ScrollTrigger Debug

Enable ScrollTrigger markers in development:

ScrollTrigger.config({ markers: true });

Performance Considerations

Asset Loading

Animation assets only load on pages with animated blocks
Scripts load in footer for better page performance
CSS provides instant styling without layout shifts

Animation Performance

Uses CSS transforms for better performance
GPU acceleration enabled by default
Respects user motion preferences
Provides smooth scroll enhancements

Memory Management

Intersection Observers are disconnected after use
ScrollTrigger instances are properly managed
No memory leaks in animation cleanup

Troubleshooting

Common Issues

Animations not running:

Check if GSAP is loaded: console.log(window.gsap)
Verify data attributes in HTML
Check browser console for errors
Ensure blocks have animation enabled in editor

ScrollTrigger animations not working:

Verify ScrollTrigger plugin is loaded
Check start/end position values
Ensure trigger element exists
Test without scrub first

Performance issues:

Reduce number of animated elements
Use simpler animations
Check for conflicting CSS animations
Test on lower-end devices

Browser DevTools

Use browser DevTools to:

Inspect data attributes on elements
Monitor animation performance
Check for JavaScript errors
Test with reduced motion simulation