Animation Controls – Technical Reference

This document provides technical implementation details for the Linchpin Blocks animation controls system.

📚 For complete user documentation, see Animation Controls

Technical Features

Visual Indicators: Small play icon appears on blocks with animation enabled
Organized Controls: Tabbed interface with Animate In, Animate Out, and Pin panels
Conditional Visibility: Controls show/hide based on dependencies and settings
Animation Preview: Test animations directly in the block editor
ScrollTrigger Integration: Full support for GSAP ScrollTrigger features including pinning and snapping
Advanced Pin Controls: Comprehensive pinning options for immersive scroll experiences
Extensible: Developers can extend supported blocks using filters

Supported Blocks

By default, animation controls are added to these container blocks:

core/group
core/row
core/columns
core/stack
core/grid

Extending Supported Blocks

Developers can add animation support to additional blocks using the provided filter:

import { addFilter } from '@wordpress/hooks';

// Add animation support to custom blocks
addFilter(
    'linchpin.animationControls.supportedBlocks',
    'my-plugin/add-animation-blocks',
    (blocks) => {
        return [
            ...blocks,
            'my-plugin/custom-block',
            'core/image',
            'core/heading'
        ];
    }
);

Animation Types

Preset Animations

Fade In: Simple opacity transition
Slide In Up/Down/Left/Right: Movement with opacity
Scale In: Scale and opacity transition
Rotate In: Rotation with opacity
Custom: Define your own transform values

Custom Animations

When "Custom" is selected, you can define specific from/to values for:

X/Y position
Scale
Rotation
Opacity

ScrollTrigger Features

Trigger Types

In View: Animation triggers when element enters viewport
Animate on Scroll: Animation progress tied to scroll position

ScrollTrigger Options

Start/End Positions: Define trigger points (e.g., "top 80%", "center center")
Scrub Animation: Link animation progress to scroll position
Scrub Smoothness: Control scrubbing responsiveness (0.1-5)
Auto Refresh: Automatically refresh on layout changes

Pin & Snap Features

Pin Settings

The dedicated Pin tab provides comprehensive control over ScrollTrigger pinning functionality:

Basic Pin Options

Enable Pinning: Pin element in place during scroll
Pin Type: Choose between fixed (default, more performant) or transform (better for nested elements)
Pin Spacing: Toggle spacing that pushes down content below the pinned element
Anticipate Pin: Anticipate pinning slightly ahead (helps prevent jumps on slower devices)
Pin Reparent: Temporarily reparent pinned element to avoid clipping issues with overflow: hidden parents

Advanced Pin Options

Pinned Container: Specify a CSS selector for a container element to pin within
Pin Spacer: Add a custom CSS class to the spacer element created during pinning

Snap Settings

Configure precise scroll snapping behavior:

Snap Type: Choose None, Mandatory (always snaps), or Proximity (snaps when close)
Snap Duration: Duration of snap animation in seconds (0.1-5s)
Snap Delay: Delay before snap animation starts (useful to wait for user to stop scrolling)
Snap Ease: Easing function for snap animation (Power1-4, Back, Elastic, Expo)
Directional Snap: Only snap when scrolling in the same direction as the scroll trigger

Best Practices: Combine pinning with scrubbing for scroll-linked animations, or use pinning alone for sticky effects. Snap works best with full-height sections for optimal user experience.

Animation Properties

Timing

Duration: Animation length in seconds
Delay: Delay before animation starts
Easing: Choose from various GSAP easing functions
Stagger: Delay between child element animations

Transform Properties (Custom mode)

Position: X/Y coordinates
Scale: Size transformation
Rotation: Rotation in degrees
Opacity: Transparency level

Usage

Select a supported block in the block editor
Open the block settings sidebar
Find the "Block Animation" panel
Configure settings across the three tabs:
- Animate In: Enable and configure entrance animations, ScrollTrigger settings, and child animation options
- Animate Out: Configure exit animations when elements leave the viewport
- Pin: Configure pinning and snap settings for immersive scroll experiences

Visual Indicators

When animation is enabled on a block, a small blue play icon appears in the top-right corner of the block in the editor. This provides immediate visual feedback about which blocks have animations configured.

Preview Functionality

The animation preview feature allows you to test animations directly in the block editor:

Enable animation on a block
Configure your animation settings
Click "Show Preview" in the Animation panel
Use "Preview Animation" to test the animation

Note: ScrollTrigger animations will only work on the frontend, but the preview shows the basic animation behavior.

Frontend Functionality

✅ Complete frontend implementation included!

The animation controls include both block editor interface AND frontend execution:

Block Editor: Visual controls for configuring animations
Frontend: Automatic execution of animations on live website
Performance: Smart asset loading only when needed
Accessibility: Respects user motion preferences

See FRONTEND.md for detailed frontend implementation documentation.

Dependencies

This module requires:

GSAP library loaded on the page
GSAP ScrollTrigger plugin (when using scroll-based animations)
WordPress block editor environment
Modern browser with Intersection Observer support (for frontend)

File Structure

animation-controls/
├── index.js              # Main filter setup and block registration
├── controls.js           # React components for control panels
├── animation-indicator.js # Visual indicator component
├── animation-preview.js   # Preview functionality
├── frontend.js           # Frontend animation execution
├── styles.scss           # Component styling (editor + frontend)
├── README.md             # This documentation
└── FRONTEND.md           # Frontend implementation details

Technical Implementation

The module uses WordPress block editor filters to:

editor.BlockEdit: Adds the animation controls and visual indicators to supported blocks
blocks.registerBlockType: Adds animation-related attributes to block schemas
linchpin.animationControls.supportedBlocks: Allows filtering of supported block types

The implementation follows WordPress coding standards and uses modern React patterns with hooks and functional components.