✨Mouse Trail
This script creates a mouse-following image trail effect using GSAP only (no CSS stylesheets, no native event listeners).All interaction is handled via GSAP Observer and GSAP Ticker.
1. Where This Code Lives (Global Scope)
This script is added in the global settings, not on a single page.
What this means:
- It runs on all pages
- Any change affects the entire website
- You only edit it once
Where to find it:
- Site Settings → Custom Code (Head)
- Global <head> embed
- Main layout / global template
- Project-wide custom code
What This Script Does:
- Images follow cursor movement
- Images fade in, move, and fade out
- No CSS animations
- No native JS listeners
- Fully powered by GSAP + Observer
2. Required HTML structure
The GSAP mouse trail works only if this exact structure is present.Each element has a specific role in the animation.
What each element does:
- .hero → main section where effect is active
- .image_wrap → animation container (relative positioning)
- .content_img-wrap → animated item (trail element)
- .content_img → image that fades/scales out
⚠️ If class names don’t match → animation will not work.
3. Main settings you are allowed to change
These are the only values most users should touch.
3.1. Distance threshold (D)
What it controls:
- How far the mouse must move before spawning the next image
Effect on animation:
- Lower value (40–60) → more images, denser trail
- Higher value (120–160) → fewer images, cleaner trail
Recommended values:
- Smooth & rich → 60–80
- Minimal & elegant → 100–140
💡 Performance tip: Higher values = fewer animations = better performance.
3.2. Fade-in speed (IN)
What it controls:
- How fast a new image appears
Effect on feeling:
- Lower (0.1) → snappy, sharp
- Higher (0.3–0.4) → softer, cinematic
Recommended:
- Fast UI → 0.12–0.18
- Luxury/editorial → 0.25–0.35
3.3. Follow / movement duration (MOVE)
What it controls:
- How long the image travels from previous point to new point
Effect on smoothness:
- Lower (0.25) → aggressive, energetic
- Higher (0.6–0.8) → slow, floaty motion
Recommended:
- Responsive UI → 0.3–0.4
- Calm premium feel → 0.55–0.7
3.4. Fade-out duration (OUT)
What it controls:
- How fast images disappear
Effect:
- Lower → sharp cut
- Higher → smooth dissolve
Recommended:
- Clean → 0.15–0.25
- Dreamy → 0.35–0.5
3.5. End scale (SCALE)
What it controls:
- Image size at the end of animation
Effect:
- Lower (0.4) → strong shrink
- Higher (0.85–1) → barely shrinks
Visual style guide:
- Artistic → 0.45–0.6
- Minimal → 0.75–0.9
4. How to disable the effect safely
Temporary disable:
Full removal:
5. Common mistakes to avoid 🚫
- Renaming class names without updating JS
- Adding CSS positioning to .content_img-wrap
- Setting overflow: hidden on .image_wrap
- Making D too small (performance issues)
6. Final advice
If you want:
- More images → decrease D
- Smoother feel → increase MOVE
- Softer visuals → increase OUT
- Snappier UI → decrease IN
💡 Change one value at a time and test.mance.
🎯 Split Text Animation
(Attribute-based)
This animation is triggered automatically when specific data attributes are added to an element.No extra JavaScript is required from the user.
1. How it works
- data-split_fade - enables split-text fade animation for the element. When this attribute is present, the text will be animated character-by-character or line-by-line.
- data-split_element - defines the text element that will be split and animated. The script looks for this attribute to know what text to process.
When both attributes are detected:
- The text is automatically split into smaller units (chars / words / lines)
- GSAP animates opacity and position
- The animation plays on page load or on scroll (depending on setup)
💡 Result: The heading will fade in smoothly with a split text effect.
What happens behind the scenes:
- Text content is wrapped into spans by the GSAP Split logic
- Each span receives a staggered animation
- Opacity and transform values are animated progressively
Common use cases:
- Hero titles
- Section headings
- Quotes
- Call-to-action text
Important rules:
- Attributes must be present
- Works only on text-based elements (h1–h6,p,span,a)
- Avoid line breaks (<br>) inside animated text
- Do not wrap split text inside other animated elements
Visual behavior summary:
- Short text → faster, punchy animation
- Long text → smoother, more cinematic reveal
.gif)
