GSAP Animation Integration
Relevant source files
The following files were used as context for generating this wiki page:
The GSAP Animation Integration in the Wasalny landing page provides a robust framework for high-performance, scroll-driven, and interactive animations. Built on top of the GreenSock Animation Platform (GSAP), the system leverages @gsap/react for seamless integration with React 19's lifecycle and ScrollTrigger for complex viewport-based transitions.
The architecture is centralized through a core configuration file that registers necessary plugins and exports utility helpers, which are then consumed by specialized custom hooks and UI components. This ensures consistency across the application, particularly for Right-to-Left (RTL) support and standardized easing presets.
Sources: src/lib/gsap.ts, src/hooks/useAnimations.ts, src/App.tsx:1-15
Core Configuration and Utilities
The project initializes GSAP globally by registering the ScrollTrigger and useGSAP plugins. A central configuration utility provides standardized easing, durations, and RTL helpers to handle the Arabic layout requirements.
RTL Animation Logic
Since the application targets an Arabic-speaking audience, the GSAP configuration includes specialized helpers to handle horizontal animations. The rtlX function detects the document direction and negates horizontal values if the direction is set to 'rtl', ensuring that "slide-in" effects move in the correct direction regardless of the locale.
Sources: src/lib/gsap.ts:1-20
Animation Presets
The system defines a set of reusable animation configurations and presets to maintain visual harmony across the landing page.
| Category | Option | Value / Description |
|---|---|---|
| Easing | easeOut | "power2.out" |
| Easing | elastic | "elastic.out(1, 0.3)" |
| Duration | medium | 0.6s |
| Presets | fadeInUp | y: 50, opacity: 0, duration: 0.6 |
| Presets | scaleIn | scale: 0.9, opacity: 0, duration: 0.6 |
Sources: src/lib/gsap.ts:25-55
Custom Animation Hooks
The project utilizes a library of custom React hooks located in src/hooks/useAnimations.ts. These hooks abstract complex GSAP logic into reusable interfaces for common web patterns.
Text and Reveal Patterns
useTextReveal: Uses thesplit-typelibrary to break text into lines, words, or characters, then applies staggered animations as the text enters the viewport.useBatchReveal: Specifically designed for grids (e.g., feature cards or route cards), this hook usesScrollTrigger.batch()to animate multiple elements with a shared stagger interval.useSectionReveal: A simpler version of batch reveal that animates the direct children of a container element.
Interactive Effects
useMagneticButton: Calculates the distance between the mouse cursor and an element's center to apply a "magnetic" pull effect using GSAP'squickTomethod for optimized performance.useTiltEffect: Implements a 3D perspective rotation on cards based on mouse position within the element.useFloatingAnimation: Creates a continuous "yoyo" animation to simulate floating, often used for hero imagery.
Scroll-Driven Dynamics
useParallax: Adjusts the vertical position of an element relative to the scroll progress.useDrawPath: Animates thestrokeDashoffsetof SVG paths, commonly used for the animated map routes.useScrollProgress: A utility hook that returns a numeric value (0 to 1) representing the scroll position within a specific container.
Sources: src/hooks/useAnimations.ts:1-150, src/hooks/useAnimations.ts:220-300
Animation Architecture Flow
The following diagram illustrates how animation logic flows from the core configuration through hooks to the UI components.
The diagram shows the dependency chain where gsap.ts acts as the source of truth for configuration, which is consumed by hooks and subsequently implemented in UI sections.
Sources: src/lib/gsap.ts, src/hooks/useAnimations.ts, src/App.tsx
Component Implementations
Page Loader Sequence
The PageLoader component uses a GSAP timeline to coordinate a multi-stage entrance and exit sequence.
- Logo Entrance: Scales and rotates the brand logo using
back.outeasing. - Text Reveal: Fades and slides the brand name.
- Progress Bar: Scales a horizontal bar from 0 to 1 over the
minDuration. - Slide Out: Once complete, the entire container slides vertically out of view (
yPercent: -100).
Sources: src/components/ui/PageLoader.tsx:15-60
Animated Map and Routes
The RoutesSection features a complex SVG animation.
- Path Drawing: Uses
useDrawPathwithscrub: trueto tie the drawing of the Nile and route lines to the scrollbar. - Pulse Markers: Continuous animations on SVG circles to highlight key locations (Damietta, Cairo, Airport).
- Object Tracking: An "animated car" (SVG circle) follows the calculated length of a path using an
onUpdatecallback within a GSAP tween.
Sources: src/components/sections/RoutesSection.tsx:120-200
Sequence of Route Map Animation
This sequence demonstrates the coordinate-based tracking system used to move the car along the map routes.
Sources: src/components/sections/RoutesSection.tsx:195-215
Summary of Integration Patterns
| Pattern | Component/Hook | Trigger Type | Implementation Detail |
|---|---|---|---|
| Entrance | AnimatedCard | Scroll (top 92%) | gsap.fromTo with y-offset |
| Batch | useBatchReveal | Scroll (top 90%) | ScrollTrigger.batch for lists |
| Interactive | useMagneticButton | Mouse Move | gsap.quickTo for x/y properties |
| Continuous | useFloatingAnimation | Infinite Loop | yoyo: true, repeat: -1 |
| SVG Path | useDrawPath | Scroll Scrub | strokeDashoffset manipulation |
Sources: src/hooks/useAnimations.ts, src/components/ui/AnimatedCard.tsx:20-40, src/lib/gsap.ts:80-95
The GSAP integration in this project provides a high degree of polish by combining declarative React components with imperative animation logic. By centralizing configurations and utilizing custom hooks, the architecture remains maintainable while delivering complex visual feedback like 3D tilts, magnetic interactions, and scroll-linked SVG path animations.