ReadmeDependencies(1)Versions(2)

@hive-academy/angular-gsap


> 🎬 GSAP-powered scroll animations for Angular applications

A modern Angular library providing declarative, scroll-triggered animations using GSAP and ScrollTrigger. Create stunning scroll experiences with minimal code.

✨ Features

- 🎯 Declarative API - Configure animations via simple inputs
- 📜 Scroll Triggers - Animate elements based on scroll position
- 👁️ Viewport Animations - Trigger animations when elements become visible
- 🎭 Hijacked Scroll - Create scroll-jacked step-by-step sequences
- 🌐 SSR Compatible - Safely handles server-side rendering
- 🎨 12+ Built-in Animations - Fade, slide, scale, parallax, bounce, flip, and more
- 🔧 Fully Customizable - Use GSAP TweenVars for complete control
- 📦 Tree-Shakeable - Import only what you need
- 🎓 TypeScript First - Full type safety and IntelliSense support

> Scope: This library provides DOM scroll animation utilities. For Three.js object animations, see @hive-academy/angular-3d.

---

📦 Installation

``bash
npm install @hive-academy/angular-gsap gsap lenis
`

Peer Dependencies:

| Package | Version | Purpose |
| ----------------- | ------- | ---------------------------- |
| @angular/core | ~20.3.0 | Angular framework |
| @angular/common | ~20.3.0 | Angular common utilities |
| gsap | ^3.14.2 | GreenSock Animation Platform |
| lenis | ^1.3.16 | Smooth scroll library |

---

🚀 Quick Start

$3

`typescript
import { Component } from '@angular/core';
import { ScrollAnimationDirective } from '@hive-academy/angular-gsap';

@Component({
selector: 'app-hero',
standalone: true,
imports: [ScrollAnimationDirective],
template:

Welcome to Angular GSAP

,
})
export class HeroComponent {}
`

$3

`typescript
import { Component } from '@angular/core';
import { ScrollAnimationDirective } from '@hive-academy/angular-gsap';

@Component({
selector: 'app-parallax',
standalone: true,
imports: [ScrollAnimationDirective],
template:
scrollAnimation
[scrollConfig]="{
animation: 'parallax',
speed: 0.5,
scrub: true
}"
class="background-image"
>
Parallax Background

,
})
export class ParallaxComponent {}
`

$3

`typescript
import { Component } from '@angular/core';
import { HijackedScrollTimelineComponent, HijackedScrollItemDirective } from '@hive-academy/angular-gsap';

@Component({
selector: 'app-tutorial',
standalone: true,
imports: [HijackedScrollTimelineComponent, HijackedScrollItemDirective],
template:

Step 1

First concept explanation

Step 2

Second concept

Step 3

Final step

,
})
export class TutorialComponent {}
`

---

📚 API Reference

$3

Applies GSAP-powered scroll-triggered animations to DOM elements.

Selector: [scrollAnimation]

Inputs:

- scrollConfig?: ScrollAnimationConfig - Animation configuration

Public Methods:

- refresh(): void - Manually refresh ScrollTrigger
- getProgress(): number - Get current scroll progress (0-1)
- setEnabled(enabled: boolean): void - Enable/disable animation

Built-in Animations:

- fadeIn, fadeOut - Opacity transitions
- slideUp, slideDown, slideLeft, slideRight - Slide animations
- scaleIn, scaleOut - Scale transitions
- parallax - Parallax movement
- custom - Use custom from/to values

Example with Custom Animation:

`typescript
[scrollConfig]="{
animation: 'custom',
from: { scale: 0.8, rotation: -10, opacity: 0 },
to: { scale: 1, rotation: 0, opacity: 1 },
duration: 1.2,
ease: 'back.out'
}"
`

---

$3

Triggers GSAP animations when elements enter the viewport using IntersectionObserver. Unlike ScrollAnimationDirective which links animations to scroll progress, this simply plays animations when elements become visible.

Selector: [viewportAnimation]

Inputs:

- viewportConfig?: ViewportAnimationConfig - Animation configuration

Outputs:

- viewportEnter: void - Emits when element enters viewport
- viewportLeave: void - Emits when element leaves viewport
- animationComplete: void - Emits when animation completes

Public Methods:

- replay(): void - Replay animation
- reset(): void - Reset element to initial hidden state

Built-in Animations:

- fadeIn, fadeOut - Opacity transitions
- slideUp, slideDown, slideLeft, slideRight - Slide animations
- scaleIn, scaleOut - Scale transitions
- rotateIn - Rotation animation
- flipIn - 3D flip animation
- bounceIn - Elastic bounce effect
- custom - Use custom from/to values

Example - Simple fade-in:

`typescript
import { Component } from '@angular/core';
import { ViewportAnimationDirective } from '@hive-academy/angular-gsap';

@Component({
selector: 'app-hero',
standalone: true,
imports: [ViewportAnimationDirective],
template:

I fade in when visible!

,
})
export class HeroComponent {}
`

Example - Bounce-in effect:

`html
viewportAnimation
[viewportConfig]="{
animation: 'bounceIn',
duration: 0.8,
threshold: 0.3
}"
>
⚡ Bounces in when 30% visible



`

Example - Staggered children:

`html


• Item 1 (appears first)


• Item 2 (0.1s delay)


• Item 3 (0.2s delay)


`

ViewportAnimationConfig:

`typescript
interface ViewportAnimationConfig {
animation?: ViewportAnimationType; // 'fadeIn', 'slideUp', etc.
duration?: number; // Default: 0.6
delay?: number; // Default: 0
ease?: string; // Default: 'power2.out'
threshold?: number; // Visibility threshold 0-1, default: 0.1
rootMargin?: string; // IntersectionObserver margin, default: '0px'
once?: boolean; // Play once or reverse on leave, default: true
stagger?: number; // Stagger delay for children
staggerTarget?: string; // CSS selector for stagger targets
from?: gsap.TweenVars; // Custom starting values
to?: gsap.TweenVars; // Custom ending values
distance?: number; // Slide distance in px, default: 50
scale?: number; // Scale factor, default: 0.9
rotation?: number; // Rotation degrees, default: 15
waitFor?: () => boolean; // Delay animation until condition is met
}
`

waitFor Example - Coordinate with loading state:

`html

viewportAnimation
[viewportConfig]="{
animation: 'slideUp',
duration: 0.8,
waitFor: preloadState.isReady
}"
>
Animates only after scene loads

`

When to use which directive:

| Use Case | Directive |
| ---------------------------------------- | ---------------------------- |
| Simple "appear when visible" animations | ViewportAnimationDirective |
| Scroll-progress linked (parallax, scrub) | ScrollAnimationDirective |
| Pinned/hijacked scroll sequences | HijackedScrollDirective |

---

$3

Creates scroll-jacked sequences where viewport is pinned while scrolling through steps.

Selector: [hijackedScroll]

Inputs:

- scrollHeightPerStep?: number - Scroll height per step in vh (default: 100)
- animationDuration?: number - Animation duration in seconds (default: 0.3)
- ease?: string - GSAP easing function (default: 'power2.out')
- markers?: boolean - Show debug markers (default: false)
- minHeight?: string - Container minimum height (default: '100vh')
- start?: string - ScrollTrigger start point (default: 'top top')
- end?: string - ScrollTrigger end point (optional, auto-calculated)

Outputs:

- currentStepChange: number - Emits current step index
- progressChange: number - Emits scroll progress (0-1)

Public Methods:

- refresh(): void - Refresh ScrollTrigger calculations
- getProgress(): number - Get current progress
- jumpToStep(index: number): void - Jump to specific step

---

$3

Marks elements as steps in a hijacked scroll sequence.

Selector: [hijackedScrollItem]

Inputs:

- slideDirection?: 'left' | 'right' | 'up' | 'down' | 'none' - Slide direction (default: 'none')
- fadeIn?: boolean - Enable fade animation (default: true)
- scale?: boolean - Enable scale animation (default: true)
- customFrom?: Record - Custom GSAP from values
- customTo?: Record - Custom GSAP to values

---

$3

Convenience wrapper component for hijacked scroll with content projection.

Selector:

Inputs: Same as HijackedScrollDirective (pass-through)

Outputs: Same as HijackedScrollDirective (pass-through)

---

$3

Scroll-driven timeline with step indicators.

Selector:

Inputs:

- steps: StepData[] - Array of step data
- scrub?: boolean | number - Link animation to scroll progress
- markers?: boolean - Show debug markers

---

$3

Step indicator with progress visualization.

Selector:

Inputs:

- steps: StepData[] - Array of step data
- currentStep: number - Currently active step index
- progress: number - Animation progress (0-1)

---

$3

#### FeatureShowcaseTimelineComponent

Scroll-driven feature showcase with alternating layouts.

Selector:

Inputs:

- scrollHeightPerStep?: number - Scroll height per feature (default: 150vh)
- animationDuration?: number - Animation duration in seconds
- markers?: boolean - Show debug markers

Example:

`html


1


Feature Title

Feature description here.

Note 1
Note 2

`

#### FeatureStepComponent

Individual feature step container.

Selector:

---

$3

#### SplitPanelSectionComponent

Parallax split-panel layout with sticky positioning.

Selector:

Inputs:

- imagePosition?: 'left' | 'right' - Image side position
- parallaxStrength?: number - Parallax movement strength

Example:

`html




1

Feature Title

Feature description.

Feature 1
Feature 2

`

---

$3

Container for parallax split-scroll sections.

Selector:

---

⚙️ Configuration

$3

`typescript
interface ScrollAnimationConfig {
// Animation type
animation?: AnimationType;

// ScrollTrigger settings
trigger?: string; // CSS selector or 'self'
start?: string; // e.g., 'top 80%'
end?: string;
scrub?: boolean | number; // Link to scroll
pin?: boolean;
markers?: boolean;

// Animation properties
duration?: number;
delay?: number;
ease?: string;

// Parallax
speed?: number;

// Custom animations
from?: gsap.TweenVars;
to?: gsap.TweenVars;

// Callbacks
onEnter?: () => void;
onLeave?: () => void;
onUpdate?: (progress: number) => void;

// Performance
once?: boolean; // Run only once

// Coordination
waitFor?: () => boolean; // Delay animation until condition is met
}
`

waitFor Example - Coordinate with loading state:

`html

scrollAnimation
[scrollConfig]="{
animation: 'parallax',
speed: 0.5,
waitFor: preloadState.isReady
}"
>
Parallax starts only after scene loads



`

$3

The library automatically handles server-side rendering:

- GSAP plugins register only in browser environment
- Animations initialize only after component renders
- No hydration mismatches

`typescript
// ✅ Safe - library handles SSR internally


Content

// ✅ Safe - no additional guards needed
constructor() {
// Library uses isPlatformBrowser() internally
}
`

---

🎯 Advanced Examples

$3

`typescript
*ngFor="let item of items; let i = index"
scrollAnimation
[scrollConfig]="{
animation: 'fadeIn',
delay: i * 0.1
}"
>
{{ item }}


`typescript
import { Component } from '@angular/core';
import { HijackedScrollDirective, HijackedScrollItemDirective } from '@hive-academy/angular-gsap';

@Component({
selector: 'app-story',
standalone: true,
imports: [HijackedScrollDirective, HijackedScrollItemDirective],
template:

onProgressChange(progress: number): void {
this.progress = progress;
}
}
`

---

🎬 Live Demo

> Coming soon - Live demo application showcasing all animation types

---

Directives Reference

$3

| Directive | Selector | Description |
| --------------------------- | ---------------------- | -------------------------------- |
| ScrollAnimationDirective | [scrollAnimation] | Scroll-triggered GSAP animations |
| HijackedScrollDirective | [hijackedScroll] | Scroll hijacking container |
| HijackedScrollItemDirective | [hijackedScrollItem] | Items within hijacked scroll |
| ScrollSectionPinDirective | [scrollSectionPin] | Pin sections during scroll |

$3

| Directive | Selector | Description |
| -------------------------- | --------------------- | ------------------------------- |
| ViewportAnimationDirective | [viewportAnimation] | IntersectionObserver animations |
| SectionStickyDirective | [sectionSticky] | Sticky section behavior |
| ParallaxSplitItemDirective | [parallaxSplitItem] | Parallax item in split layout |
| LenisSmoothScrollDirective | [lenisSmoothScroll] | Enable Lenis smooth scrolling |

$3

| Directive | Selector | Description |
| --------------------------- | ---------------------- | ----------------------------- |
| FeatureBadgeDirective | [featureBadge] | Feature step badge slot |
| FeatureTitleDirective | [featureTitle] | Feature step title slot |
| FeatureDescriptionDirective | [featureDescription] | Feature step description slot |
| FeatureNotesDirective | [featureNotes] | Feature step notes slot |
| FeatureVisualDirective | [featureVisual] | Feature step visual slot |
| FeatureDecorationDirective | [featureDecoration] | Feature step decoration slot |

$3

| Directive | Selector | Description |
| ------------------------------ | ------------------------- | ---------------------------- |
| SplitPanelImageDirective | [splitPanelImage] | Split panel image slot |
| SplitPanelBadgeDirective | [splitPanelBadge] | Split panel badge slot |
| SplitPanelTitleDirective | [splitPanelTitle] | Split panel title slot |
| SplitPanelDescriptionDirective | [splitPanelDescription] | Split panel description slot |
| SplitPanelFeaturesDirective | [splitPanelFeatures] | Split panel features slot |

---

Services

$3

Core GSAP service for initialization and configuration.

Methods:

- get gsap - Access configured GSAP instance
- registerPlugin(...plugins) - Register additional GSAP plugins

Example:

`typescript
@Component({ ... })
export class MyComponent {
private gsapCore = inject(GsapCoreService);

animate() {
this.gsapCore.gsap.to('.element', { x: 100, duration: 1 });
}
}
`

---

$3

Lenis smooth scroll integration with GSAP.

Methods:

- initialize(options?) - Initialize Lenis with options
- destroy() - Clean up Lenis instance
- scrollTo(target, options?) - Scroll to target
- stop() / start() - Pause/resume smooth scrolling

Properties:

- scroll$ - Observable of scroll events
- progress$ - Observable of scroll progress (0-1)

Example:

`typescript
@Component({ ... })
export class MyComponent {
private lenis = inject(LenisSmoothScrollService);

scrollToSection() {
this.lenis.scrollTo('#section-2', { duration: 1.5 });
}
}
`

---

Configuration Providers

$3

Configures GSAP globally using Angular's modern provider pattern.

Usage:

`typescript
// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideGsap } from '@hive-academy/angular-gsap';

export const appConfig: ApplicationConfig = {
providers: [
provideGsap({
defaults: {
ease: 'power2.out',
duration: 1,
},
}),
],
};
`

Options:

`typescript
interface GsapConfig {
defaults?: gsap.TweenVars; // Default tween properties
plugins?: GSAPPlugin[]; // Additional plugins to register
}
`

---

$3

Configures Lenis smooth scrolling globally.

Usage:

`typescript
// app.config.ts
import { provideGsap, provideLenis } from '@hive-academy/angular-gsap';

export const appConfig: ApplicationConfig = {
providers: [
provideGsap(), // GSAP must be provided first
provideLenis({
lerp: 0.1, // Smoothness (0.05-0.1 recommended)
wheelMultiplier: 1, // Mouse wheel speed
touchMultiplier: 2, // Touch swipe speed
smoothWheel: true, // Smooth mouse wheel
}),
],
};
`

Options:

`typescript
interface LenisServiceOptions {
lerp?: number; // Smoothness factor
wheelMultiplier?: number; // Mouse wheel sensitivity
touchMultiplier?: number; // Touch sensitivity
smoothWheel?: boolean; // Enable smooth wheel
useGsapTicker?: boolean; // Sync with GSAP ticker
}
`

---

📖 Resources

- GSAP Documentation
- ScrollTrigger Docs
- Angular Documentation

---

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide and follow the conventional commit format for all commits.

See CODE_OF_CONDUCT.md for community guidelines.

---

📄 License

MIT © Hive Academy

---

🔗 Related Packages

- @hive-academy/angular-3d` - Three.js integration for Angular (for 3D object animations)