hypnagaga_old/docs/GSAP_ANIMATIONS.md

GSAP Scroll Animations Guide

GSAP scroll-driven animations for photographs and content. Animations are controlled by scroll position—scrolling down plays forward, scrolling up plays backward.

Quick Start

{% gsapScrollAnim {
  "animationType": "fadeIn",
  "scrollStart": "top 80%"
} %}
[{
  "src": "/path/to/image.jpg",
  "alt": "Image description",
  "caption": "Optional caption"
}]
{% endgsapScrollAnim %}

Configuration Options

All parameters are optional with sensible defaults:

{
  "animationType": "fadeIn",      // Animation preset (see below)
  "scrollStart": "top 80%",       // When animation starts
  "scrollEnd": "bottom 20%",      // When animation completes
  "scrub": true,                  // Tied to scroll position (bidirectional)
  "containerClass": "gsap-container", // CSS class for wrapper
  "pin": false,                   // Pin element during animation
  "markers": false                // Show debug markers (dev only)
}

Animation Presets

• fadeIn - Fade in from below (opacity + translate Y)
• fadeInUp - Fade in from further below
• fadeInDown - Fade in from above
• scaleIn - Scale up with fade in (with bounce effect)
• slideInLeft - Slide in from left side
• slideInRight - Slide in from right side
• parallax - Subtle vertical parallax effect
• stagger - Sequential animation for multiple items
• zoomIn - Start with full image, zoom into focal point
• zoomOut - Start zoomed into focal point, pull back to full image

Image Format

Images are defined as JSON array inside the paired shortcode:

[{
  "src": "/path/to/image.jpg",
  "alt": "Required alt text",
  "caption": "Optional caption text"
}, {
  "src": "/path/to/image2.jpg",
  "alt": "Second image",
  "caption": "Another caption"
}]

Images are automatically optimized via Eleventy Image plugin (WebP/JPEG, responsive sizes).

Examples

Single Image with Fade In

{% gsapScrollAnim {
  "animationType": "fadeIn"
} %}
[{
  "src": "/images/photo.jpg",
  "alt": "Description"
}]
{% endgsapScrollAnim %}

Multiple Images with Stagger

{% gsapScrollAnim {
  "animationType": "stagger",
  "scrollStart": "top 70%"
} %}
[{
  "src": "/images/photo1.jpg",
  "alt": "First photo",
  "caption": "Photo 1"
}, {
  "src": "/images/photo2.jpg",
  "alt": "Second photo",
  "caption": "Photo 2"
}]
{% endgsapScrollAnim %}

Parallax Effect

{% gsapScrollAnim {
  "animationType": "parallax",
  "scrub": true
} %}
[{
  "src": "/images/background.jpg",
  "alt": "Background scene"
}]
{% endgsapScrollAnim %}

Custom Container Class

{% gsapScrollAnim {
  "animationType": "scaleIn",
  "containerClass": "gsap-container featured-image"
} %}
[{
  "src": "/images/hero.jpg",
  "alt": "Hero image"
}]
{% endgsapScrollAnim %}

Zoom In to Focal Point

Draw attention to a specific detail in a high-resolution photograph:

{% gsapScrollAnim {
  "animationType": "zoomIn",
  "focalX": 75,
  "focalY": 25,
  "startZoom": 1,
  "endZoom": 2.5
} %}
[{
  "src": "/images/detail-photo.jpg",
  "alt": "Macro photography showing fine detail"
}]
{% endgsapScrollAnim %}

Zoom Parameters:

• focalX (0-100): Horizontal focal point percentage from left (default: 50)
• focalY (0-100): Vertical focal point percentage from top (default: 50)
• startZoom: Initial scale (default: 1 = 100%)
• endZoom: Final scale (default: 2.5 = 250%)

zoomIn: Starts with full image visible, zooms into the focal point zoomOut: Starts zoomed into focal point, pulls back to show full image

High-resolution images (up to 3200px) are automatically loaded for zoom animations to preserve detail when scaled.

ScrollTrigger Settings

scrollStart / scrollEnd

Control when the animation begins and ends relative to viewport:

• "top bottom" - Element's top enters viewport bottom
• "top 80%" - Element's top at 80% viewport height
• "center center" - Element center aligns with viewport center
• "bottom top" - Element bottom exits viewport top

Default: scrollStart: "top 80%", scrollEnd: "bottom 20%"

scrub

When true (default), animation progress is tied directly to scroll position, enabling bidirectional playback.

When false, animation plays once when scroll position crosses scrollStart threshold.

CSS Customization

Default wrapper class: .gsap-container

Generated structure:

<div class="gsap-container" data-gsap-scroll-anim='{...}'>
  <div class="gsap-item">
    <figure class="gsap-image-wrapper">
      <picture>
        <img class="gsap-image" src="..." alt="...">
      </picture>
      <figcaption>...</figcaption>
    </figure>
  </div>
</div>

Add custom styles in your CSS:

.gsap-container.featured-image {
  max-width: 1200px;
  margin: 0 auto;
}

.gsap-item {
  margin-bottom: 2rem;
}

Accessibility

• Respects prefers-reduced-motion - animations disabled automatically
• All images require alt text
• ScrollTrigger callbacks maintain proper ARIA states

Turbo Drive Compatibility

Animations are automatically cleaned up and re-initialized on Turbo navigation:

• Contexts reverted before page change
• ScrollTrigger instances killed
• Re-initialized after new page loads

Debugging

Enable debug markers to visualize scroll trigger points:

{% gsapScrollAnim {
  "animationType": "fadeIn",
  "markers": true
} %}
[...]
{% endgsapScrollAnim %}

This shows colored markers in viewport indicating trigger start/end positions.

Performance

• Animations use GPU-accelerated properties (transform, opacity)
• will-change applied for optimization
• ScrollTrigger efficiently batches calculations
• Contexts properly cleaned up on navigation

Files Modified

• Shortcode: src/_config/shortcodes/gsap.js
• Initializer: src/assets/scripts/bundle/gsap-shortcode-init.js
• CSS: src/assets/css/global/utilities/gsap-animations.css
• Config: Registered in eleventy.config.js as paired shortcode