Troubleshooting

beginner

Common issues and fixes — invisible elements, animations not triggering, GSAP licensing, and cache problems.

Elements Are Invisible (Not Animating)

This is the most common issue. Check in order: 1) Is the trigger attribute set? You need BOTH data-etch-motion="preset-name" AND data-etch-motion-trigger="scroll". The trigger tells the scanner which GSAP modules to load. Without it, ScrollTrigger won't be enqueued and scroll animations can't fire. 2) Check browser console for JavaScript errors. 3) Verify GSAP vendor files exist in etch-motion/assets/vendor/gsap/. 4) Check if reduced motion is enabled in your OS.

<!-- WRONG: Missing trigger -->
data-etch-motion="fade-up"

<!-- CORRECT: Both attributes -->
data-etch-motion="fade-up"
data-etch-motion-trigger="scroll"

The trigger attribute is the #1 cause of invisible elements. The preset JSON defines default triggers, but the PHP scanner needs to see the trigger string in the HTML to know which modules to enqueue.

Animations Work on Some Pages But Not Others

The plugin scans each page's content independently. If a page template doesn't go through the normal WordPress content pipeline (custom templates, shortcodes, AJAX content), the scanner may miss the attributes. Fix: use the etch_motion_scan_content filter to inject template content, or etch_motion_gsap_modules to force-enqueue specific modules.

// Force ScrollTrigger on custom pages
add_filter('etch_motion_gsap_modules', function($modules) );

GSAP Licensing

Since April 2025, GSAP is free for commercial use under the Standard No Charge License following Webflow's acquisition. All plugins (ScrollTrigger, SplitText, Flip, etc.) are included. However, GSAP is not GPL-compatible, which is why Etch Motion is sold from its own site rather than WordPress.org. You do not need a separate GSAP license.

Etch Compatibility

Etch Motion works with and without Etch. With Etch active: builder panel integration, styles registered in etch_styles. Without Etch: initial-state CSS output via wp_head, all animation functionality identical, just no builder panel. The plugin detects Etch via defined('ETCH_VERSION').

Cache Issues

If animations don't appear after adding attributes, clear your page cache. The scanner runs on each request, but cached pages serve the old HTML. Clear the cache for that page or do a full flush after adding data-etch-motion attributes.