Custom Hooks & Utilities
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The "Custom Hooks & Utilities" layer forms the architectural backbone for the Wasalny landing page's interactive experience. This system leverages React 19, GSAP (GreenSock Animation Platform), and Tailwind CSS v4 to provide a declarative way of managing complex animations, scroll-triggered effects, and styling logic. The primary goal is to abstract low-level DOM manipulations and animation timelines into reusable, type-safe hooks and utility functions.
The system is split into two primary domains: animation hooks (located in src/hooks/) that manage visual transitions and lifecycle-linked effects, and core utilities (located in src/lib/) that handle styling merges and global GSAP configurations, including specialized support for Right-to-Left (RTL) layouts essential for the Arabic user interface.
Sources: AGENTS.md:1-25, src/lib/gsap.ts:1-10
Animation Architecture & GSAP Integration
The project utilizes a centralized GSAP configuration to ensure consistent easing, durations, and plugin registration across the application. Plugins such as ScrollTrigger and @gsap/react are registered globally to facilitate performant scroll-based interactions.
RTL Support Logic
Given the Arabic context of the project, the utility layer includes specialized logic to handle direction-aware animations. This ensures that horizontal movements (X-axis) are correctly mirrored when the document direction is set to "rtl".
The diagram above illustrates how the rtlX utility processes animation coordinates based on document metadata.
Sources: src/lib/gsap.ts:13-23, AGENTS.md:131-138
Global Animation Configurations
Standardized presets for easing and duration are defined to maintain a cohesive feel throughout the landing page.
| Configuration | Property | Value / Preset |
|---|---|---|
| Easing | easeOut | "power2.out" |
| Easing | easeInOut | "power2.inOut" |
| Duration | fast | 0.3s |
| Duration | medium | 0.6s |
| Stagger | medium | 0.1s |
Sources: src/lib/gsap.ts:26-47
Custom React Hooks
The useAnimations.ts file contains the logic for most visual interactions. These hooks utilize the useGSAP hook for safe animation lifecycle management within React components.
Text & Reveal Hooks
The project features advanced text manipulation using SplitType to animate lines, words, or characters individually.
useTextReveal: Splits text and animates elements as they enter the viewport.useBatchReveal: Specifically designed for grid layouts (e.g., Features or Services), allowing staggered entrance for multiple elements using a selector.useSectionReveal: A simplified hook for standard vertical staggered entrance of a section's children.
Sources: src/hooks/useAnimations.ts:16-86, src/hooks/useAnimations.ts:252-297
Interactive & Physics Hooks
Beyond entry animations, several hooks provide continuous or mouse-reactive feedback:
| Hook | Purpose | Implementation Detail |
|---|---|---|
useMagneticButton | Creates a "magnetic" attraction to the mouse | Uses gsap.quickTo for high-performance X/Y updates |
useFloatingAnimation | Continuous sine-wave floating effect | Employs yoyo: true and repeat: -1 |
useTiltEffect | 3D card rotation on hover | Calculates mouse position relative to element center |
useParallax | Moves elements at different speeds while scrolling | Calculates offset based on ScrollTrigger.maxScroll |
Sources: src/hooks/useAnimations.ts:114-142, src/hooks/useAnimations.ts:193-207, src/hooks/useAnimations.ts:211-250
Interaction Data Flow
The following sequence diagram demonstrates how a reactive animation hook like useMagneticButton manages DOM events and GSAP updates.
Sources: src/hooks/useAnimations.ts:114-142
Component-Specific Animation Logic
Some utilities and hooks are integrated directly into UI components to handle specific state transitions.
Page Loading Logic
The PageLoader.tsx component uses a complex GSAP timeline to manage the initial entrance and exit of the application. It synchronizes logo scaling, text reveal, and a progress bar duration defined by minDuration.
Scroll-Triggered Headings
The SectionHeading component utilizes a localized gsap.context within a useEffect to trigger specific underline animations and container fades only when the heading is 92% from the top of the viewport.
Sources: src/components/ui/SectionHeading.tsx:24-60
Utility Functions
The project includes a standard utility for class name manipulation to support Tailwind CSS v4's dynamic styling.
cn(...inputs)
This utility combines clsx for conditional class logic and tailwind-merge to resolve styling conflicts, which is particularly important for the project's complex "Glassmorphism" and "Card" component layers.
Sources: src/lib/utils.ts:1-5, src/index.css:170-205
Summary
The "Custom Hooks & Utilities" module provides a robust, centralized framework for the Wasalny landing page's interactive features. By abstracting GSAP logic into reusable React hooks like useTextReveal and useBatchReveal, and providing RTL-aware utilities like rtlX, the architecture ensures that complex animations remain maintainable, performant, and consistent across different sections of the application.