Guide

Animation Controls – Complete Documentation

This is the comprehensive documentation for the Linchpin Blocks animation controls system, covering all features, implementation details, and user guides.

📚 Table of Contents

  1. Overview & Features
  2. User Guide
  3. Animation Types & Controls
  4. Advanced Features
  5. Interactive Guide System
  6. Frontend Implementation
  7. Developer Documentation
  8. Performance & Accessibility

Overview & Features

What is Animation Controls?

The Animation Controls system provides comprehensive GSAP animation capabilities for WordPress blocks, including:

  • 13+ Animation Types: Fade, Slide, Scale, Rotate, Reveal, Zoom, Custom
  • ScrollTrigger Integration: Complete ScrollTrigger support with pinning and snapping
  • Child Animation System: 5 patterns for animating child elements
  • Preset Management: Save, load, and share animation configurations
  • Copy/Paste Functionality: Transfer settings between blocks
  • Interactive Guide: 7-step walkthrough for new users
  • Performance Optimized: Lazy loading, GPU acceleration, accessibility support

Supported Blocks

  • core/group – Group blocks
  • core/row – Row blocks
  • core/columns – Column blocks
  • core/stack – Stack blocks
  • core/grid – Grid blocks
  • core/cover – Cover blocks
  • core/column – Individual columns

User Guide

Getting Started

  1. Select a supported block in the WordPress editor
  2. Open the block settings sidebar (Inspector Controls)
  3. Find the "Block Animation" panel – it will auto-open when animations are enabled
  4. Configure your animations using the three main tabs:
    • Animate In: Entrance animations and ScrollTrigger settings
    • Animate Out: Exit animations and toggle actions
    • Pin: Pinning and snap settings

Basic Animation Setup

Animate In (Entrance Animations)

  1. Enable Animation: Toggle the "Enable Animation" switch
  2. Choose Animation Type: Select from 13+ preset types or Custom
  3. Set Timing: Configure duration, delay, and easing
  4. ScrollTrigger Options: Enable scrubbing and set trigger positions
  5. Child Animations: Enable to animate child elements individually

Animate Out (Exit Animations)

  1. Enable Animate Out: Toggle the "Enable Animate Out" switch
  2. Choose Out Animation Type: Select from 13+ exit animation types
  3. Set Out Timing: Configure duration, delay, and easing
  4. Set Offset: Define when out animation should start
  5. Child Out Animations: Enable to animate children when exiting

Pin Controls (Sticky Effects)

  1. Enable Pinning: Toggle the "Enable Pinning" switch
  2. Choose Pin Type: Fixed (performance) or Transform (nested elements)
  3. Configure Pin Options: Spacing, anticipate pin, reparent settings
  4. Advanced Options: Custom containers, spacer classes
  5. Snap Settings: Configure scroll snapping behavior

Visual Indicators

When animations are enabled, you'll see:

  • Blue Play Button: On animated blocks (click to preview)
  • Animation Badges: In/Out animation type indicators
  • Magenta Pin Icon: On pinned blocks
  • Child Indicators: Shows linked child animations

Smart Panel Behavior

  • Auto-Open: Panel opens when animations are enabled
  • Dynamic Title: Shows current animation status
  • Intelligent Tabs: Auto-selects relevant tab
  • Visual Feedback: Green status indicators, animation summaries

Animation Types & Controls

Animation Types

Entrance Animations (Animate In)

  1. Fade In – Simple opacity transition
  2. Slide In Up/Down/Left/Right – Movement with opacity
  3. Scale In – Scale and opacity transition
  4. Rotate In – Rotation with opacity
  5. Reveal Left/Right – Column-based reveals
  6. Reveal Inward/Outward – Alternating column reveals
  7. Zoom In – Center-based scale reveal
  8. Custom – User-defined transform values

Exit Animations (Animate Out)

  1. Fade Out – Simple opacity transition
  2. Slide Out Up/Down/Left/Right – Movement with opacity
  3. Scale Out – Scale and opacity transition
  4. Rotate Out – Rotation with opacity
  5. Reveal Out Left/Right – Column-based reveals
  6. Reveal Outward/Inward – Alternating column reveals
  7. Zoom Out – Center-based scale reveal
  8. Custom – User-defined transform values

Timing & Easing Controls

Duration & Delay

  • Duration: 0.1-10 seconds with 0.1 step precision
  • Delay: 0-5 seconds with 0.1 step precision
  • Stagger: Delay between child element animations
  • Out Timing: Independent timing for exit animations

Easing Functions

  • Power Easing: Power1-4 with In/Out/InOut variants
  • Back Easing: Overshoot effects with In/Out/InOut
  • Elastic Easing: Bouncy effects with In/Out/InOut
  • Bounce Easing: Bounce effects with In/Out/InOut
  • Linear: No easing (none option)

Custom Transform Controls

When "Custom" animation type is selected:

  • Position (X/Y): Horizontal and vertical positioning
  • Scale: Size transformation (0.1-5x)
  • Rotation: Rotation in degrees (-360 to 360)
  • Opacity: Transparency (0-1)
  • From/To Values: Initial and target states
  • Out From/To Values: Exit animation states

Advanced Features

ScrollTrigger Integration

Trigger Configuration

  • Start Position: Define when animation begins (e.g., "top 80%")
  • End Position: Define when animation ends (e.g., "bottom 20%")
  • Scrub Animation: Link animation progress to scroll position
  • Scrub Smoothness: Control scrubbing responsiveness (0.1-5)
  • Auto Refresh: Automatically refresh on layout changes

Toggle Actions

  • Enter Actions: What happens when entering trigger zone
  • Leave Actions: What happens when leaving trigger zone
  • Enter Back Actions: What happens when re-entering from above
  • Leave Back Actions: What happens when re-leaving from below

Child Animation System

Animation Patterns

  1. Staggered – One after another with delay
  2. All At Once – Simultaneous animation
  3. Sequential – Same as staggered
  4. Alternating – Every other element
  5. Random – Random order animation

Child Animation Controls

  • Animate Children: Enable child element animation
  • Child Animation Type: Independent animation type for children
  • Child Animation Pattern: How children are animated
  • Child Delay: Delay between each child animation
  • Reverse Child Order: Animate from last to first
  • Child Out Animations: Separate exit animations for children

Pin & Snap Features

Pin Settings

  • Pin Enable/Disable: Master pin control
  • Pin Type: Fixed (performance) vs Transform (nested elements)
  • Pin Spacing: Control content flow around pinned elements
  • Anticipate Pin: Prevent visual jumps
  • Pin Reparent: Handle overflow issues
  • Custom Containers: Pin within specific containers
  • Pin Spacer Classes: Custom CSS for spacer elements

Snap Settings

  • Snap Type: None, Mandatory, or Proximity
  • Snap Duration: Animation duration for snap (0.1-5s)
  • Snap Delay: Delay before snap starts (0-2s)
  • Snap Ease: Easing function for snap animation
  • Directional Snap: Only snap in trigger direction

Preset Management

Save Presets

  • Preset Naming: Custom names for saved presets
  • Complete Settings: Saves all animation attributes
  • REST API Integration: Server-side preset storage
  • User-Specific: Presets tied to user accounts

Load Presets

  • Preset Selection: Dropdown of saved presets
  • Preview Modal: See preset details before applying
  • Settings Summary: Visual breakdown of preset settings
  • Apply Functionality: One-click preset application
  • Delete Presets: Remove unwanted presets

Copy/Paste Functionality

Copy Settings

  • JSON Export: Complete animation settings as JSON
  • Clipboard Integration: One-click copy to clipboard
  • Validation: Only copies when animations are enabled
  • Success Feedback: Confirmation notifications

Paste Settings

  • JSON Import: Paste animation settings from JSON
  • Modal Interface: User-friendly paste interface
  • Error Handling: Validation and error messages
  • Success Feedback: Confirmation of successful application

Interactive Guide System

7-Step Walkthrough

The system includes an interactive guide that automatically appears for first-time users:

  1. Welcome: Introduction to animation controls
  2. Animate In: Entrance animation features
  3. Animate Out: Exit animation features
  4. Pinning: Sticky scroll effects
  5. Scroll Scrubbing: Scroll-linked animations
  6. Advanced Features: Snap and advanced options
  7. Getting Started: Quick start guide

Guide Features

  • Smart Auto-Display: Shows when first enabling animations
  • Session Management: Only shows once per session
  • Permanent Dismissal: Option to never show again
  • Manual Access: Always available via More Tools menu
  • Card-Based Layout: Visual, engaging content with hover effects

Accessing the Guide

  • Automatic: Shows when first enabling any animation feature
  • Manual: Click three dots (⋮) in editor toolbar → "Show Animation Features Guide"
  • Persistent: Available even after permanent dismissal

Frontend Implementation

How It Works

Block Rendering (PHP)

When blocks are rendered on the frontend, animation data is injected as HTML attributes:

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

Animation Execution (JavaScript)

The frontend script handles animation execution:

  1. Waits for GSAP library to be available
  2. Registers ScrollTrigger plugin if needed
  3. Finds all animated elements via data attributes
  4. Initializes animations for each element

Animation Types

  • In-View Animations: Uses Intersection Observer API
  • Scroll-Based Animations: Uses GSAP ScrollTrigger plugin
  • Child Animations: Supports all 5 animation patterns
  • Pin & Snap: Complete ScrollTrigger pinning and snapping

Performance Optimizations

  • Lazy Loading: Assets only load when needed
  • GPU Acceleration: Hardware-accelerated animations
  • Efficient Triggers: Optimized ScrollTrigger usage
  • Memory Management: Proper cleanup and disposal

Browser Support

  • Modern Browsers: Chrome, Firefox, Safari, Edge
  • Mobile Support: iOS and Android browsers
  • Progressive Enhancement: Works without JavaScript
  • Accessibility: Respects user motion preferences

Developer Documentation

Extending Supported Blocks

Add animation support to custom blocks:

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

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

Animation Type Filtering

Control which animation types are available:

add_filter( 'linchpin_blocks_enabled_animation_types', function( $enabled_types, $all_defaults ) {
    return [
        'fadeIn',
        'fadeOut',
        'slideInUp',
        'slideInDown',
    ];
}, 10, 2 );

Technical Architecture

Modular Design

  • Component-Based: Reusable React components
  • Utility Functions: Shared animation logic
  • Hook System: Custom hooks for common functionality
  • Filter Integration: WordPress filter system

Code Organization

  • Separation of Concerns: Clear responsibility boundaries
  • Maintainability: Easy to modify and extend
  • Testability: Individual components can be tested
  • Documentation: Comprehensive inline documentation

WordPress Integration

  • Block Editor: Native block editor integration
  • REST API: Server-side preset management
  • User Meta: Persistent user preferences
  • Asset Management: Efficient script and style loading

Performance & Accessibility

Performance Optimizations

  • Lazy Loading: Assets only load when needed
  • GPU Acceleration: Hardware-accelerated animations
  • Efficient Triggers: Optimized ScrollTrigger usage
  • Memory Management: Proper cleanup and disposal

Accessibility Features

  • Reduced Motion: Respects prefers-reduced-motion
  • Keyboard Navigation: Full keyboard support
  • Screen Reader: Proper ARIA labels and descriptions
  • Focus Management: Clear focus indicators

Browser Compatibility

  • Modern Browsers: Chrome, Firefox, Safari, Edge
  • Mobile Support: iOS and Android browsers
  • Progressive Enhancement: Works without JavaScript
  • Fallback Support: Graceful degradation

Troubleshooting

Common Issues

Animations not running:

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

ScrollTrigger animations not working:

  1. Verify ScrollTrigger plugin is loaded
  2. Check start/end position values
  3. Ensure trigger element exists
  4. Test without scrub first

Performance issues:

  1. Reduce number of animated elements
  2. Use simpler animations
  3. Check for conflicting CSS animations
  4. Test on lower-end devices

Debugging Tools

  • ScrollTrigger Markers: Enable in development
  • Browser DevTools: Inspect data attributes and performance
  • Console Warnings: Check for missing dependencies
  • Network Tab: Verify asset loading

Future Enhancements

Planned Features

  • Animation Templates: Pre-built animation combinations
  • Batch Operations: Apply settings to multiple blocks
  • Animation Library: Curated animation collections
  • Advanced Easing: Custom easing function editor
  • Animation Timeline: Visual timeline editor
  • Performance Analytics: Animation performance metrics

Extensibility

  • Plugin API: Third-party animation extensions
  • Custom Presets: User-defined preset categories
  • Animation Events: JavaScript events for animations
  • Advanced Triggers: Custom trigger conditions

This comprehensive documentation covers all aspects of the Linchpin Blocks animation controls system, providing both users and developers with complete information about available functionality.

Was this helpful?