@row0902/ngx-gsap

Modern, universal GSAP directives, composables, and reactive accessibility utilities for Angular 22+. Built with Signals, Zoneless architecture, zero constructors, and @angular/cdk/a11y.

Features

• 🚀 Modern Angular 22+ Native: 100% constructor-free, Zoneless-compatible, using field initializers, inject(), input(), and output().
• ⚡ 10 Universal Directives: High-frequency interactive directives with dual selectors ([gsap...] and [app...]).
• 📦 One-Line Import: Import all 10 directives at once via the GSAP_DIRECTIVES tuple.
• ♿ Reactive Accessibility: Integrates @angular/cdk/a11y (LiveAnnouncer, CdkTrapFocus) and strict prefers-reduced-motion compliance across all directives.
• 🧹 Automatic Cleanup: Powered by DestroyRef and gsap.context() — zero memory leaks.
• 🧪 Vitest-Ready: Pre-configured acceleration strategies (timeScale(1000)) for 0ms unit tests.

Installation

# Using bun (recommended)
bun add @row0902/ngx-gsap gsap @angular/cdk

# Using npm
npm install @row0902/ngx-gsap gsap @angular/cdk

Quick Start

1. Global Setup (app.config.ts)

Register GSAP plugins once at your application root:

import { ApplicationConfig } from '@angular/core';
import { provideGsap } from '@row0902/ngx-gsap';

export const appConfig: ApplicationConfig = {
  providers: [
    provideGsap(),
  ],
};

2. Use in Any Standalone Component

import { Component, signal } from '@angular/core';
import { GSAP_DIRECTIVES } from '@row0902/ngx-gsap';

@Component({
  selector: 'app-showcase',
  imports: [GSAP_DIRECTIVES], // Imports all 10 directives in a single line!
  template: `
    <!-- Scroll Entrance -->
    <section gsapScrollReveal direction="up" [distance]="40">

      <!-- 3D Tilt Card -->
      <div gsap3dTilt [maxTilt]="15" class="card">
        <h3 [gsapTextScramble]="title()">...</h3>
        <span [gsapCountUp]="score()" prefix="+"></span>

        <!-- Tactile Button -->
        <button gsapInteractivePress (click)="toggle()">
          Toggle Details
        </button>

        <!-- Auto-Height Collapsible -->
        <div [gsapSmoothHeight]="isOpen()">
          <p>Smoothly animates real DOM height without layout jumps.</p>
        </div>
      </div>

    </section>
  `,
})
export class ShowcaseComponent {
  readonly title = signal('SYSTEM READY');
  readonly score = signal(9850);
  readonly isOpen = signal(false);

  toggle(): void {
    this.isOpen.update((v) => !v);
  }
}

Available Directives

| Directive | Library Selector | Local Selector | Description | | :--- | :--- | :--- | :--- | | Scroll Reveal | [gsapScrollReveal] | [appScrollReveal] | ScrollTrigger viewport entrance (up, down, zoom, etc.). | | 3D Tilt | [gsap3dTilt] | [app3dTilt] | Interactive 3D perspective tilt on hover using quickTo(). | | Stagger | [gsapStagger] | [appStagger] | Automatically staggers child element entrance in @for lists. | | Interactive Press | [gsapInteractivePress] | [appInteractivePress] | Tactile spring physics on hover, press down, and release. | | Smooth Height | [gsapSmoothHeight] | [appSmoothHeight] | Auto-height accordion/collapsible on boolean signal change. | | Text Scramble | [gsapTextScramble] | [appTextScramble] | Cyberpunk text decoder with screen reader announcements. | | Count Up | [gsapCountUp] | [appCountUp] | Smooth number interpolation on numeric signals with formatting. | | Magnetic Pull | [gsapMagnetic] | [appMagnetic] | Magnetic cursor pull effect for buttons and icons. | | Horizontal Scroll | [gsapHorizontalScroll] | [appHorizontalScroll] | Panoramic scroll gallery with viewport pinning and scrub. | | Render Ticker | [gsapTicker] | [appTicker] | 60/120fps GSAP ticker loop for <canvas>, WebGL, or simulations. |

Composables & Utilities

injectGSAP()

Scoped animation execution with automatic DestroyRef cleanup:

import { Component, ElementRef, viewChild } from '@angular/core';
import { injectGSAP } from '@row0902/ngx-gsap';
import { gsap } from 'gsap';

@Component({
  template: `<div #box class="box"></div>`
})
export class HeroComponent {
  private readonly box = viewChild.required<ElementRef>('box');

  private readonly anim = injectGSAP(() => {
    gsap.to(this.box().nativeElement, { rotation: 360, duration: 2 });
  });
}

injectGsapTicker()

High-frequency render loop hook for Canvas, WebGL, or D3:

import { injectGsapTicker } from '@row0902/ngx-gsap';

export class Visualizer {
  private readonly ticker = injectGsapTicker(({ time, deltaTime }) => {
    // Draw canvas frame
  });
}

License

MIT © Rowell Urbaez Reyes (Row0902)