@elm/ngx-animations

🎨 Next-Level Animation Library for Angular

Production-ready • Lightweight • High-performance • RTL Support

✨ What is @elm/ngx-animations?

A complete, production-ready Angular animation library inspired by GSAP but optimized specifically for Angular applications. Built with Angular 18+ standalone components, it provides a rich set of animation directives, components, and a powerful timeline service for creating stunning UI animations.

🎯 Key Features

🚀 High Performance - Optimized with RAF and CSS animations
📦 Standalone Components - Full Angular 18+ architecture
🌍 RTL Support - First-class Arabic and Hebrew support
🎪 GSAP-like Timeline - Chain animations with ease
💪 TypeScript First - Complete type safety
📱 Mobile Friendly - Smooth on all devices
🪶 Lightweight - Zero dependencies, tree-shakeable
♿ Accessible - Respects prefers-reduced-motion

📦 Installation

npm install @elm/ngx-animations

🚀 Quick Start

import { Component } from '@angular/core';
import { FadeInDirective, SlideInDirective } from '@elm/ngx-animations';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [FadeInDirective, SlideInDirective],
  template: `
    <div ngxFadeIn [duration]="500">
      <h1>Fade In Animation!</h1>
    </div>

    <div ngxSlideIn direction="left" [triggerOnScroll]="true">
      <p>Slides in when you scroll!</p>
    </div>
  `
})
export class AppComponent {}

👉 See QUICKSTART.md for a 5-minute getting started guide!

🎨 What's Included?

Animation Directives (6)

Directive	Description
`ngxFadeIn`	Smooth fade in/out animations
`ngxSlideIn`	Slide from any direction with RTL support
`ngxScaleIn`	Scale animations from any origin
`ngxRotateIn`	3D rotation on any axis
`ngxParallaxScroll`	Smooth parallax scrolling
`ngxRippleClick`	Material Design ripple effect

Animation Components (4)

Component	Description
`<ngx-scroll-reveal>`	Reveal content on scroll
`<ngx-stagger-list>`	Stagger list item animations
`<ngx-typewriter>`	Typewriter effect with RTL
`<ngx-marquee>`	Continuous scrolling content

Services (1)

Service	Description
`TimelineService`	GSAP-like timeline for chaining animations

📚 Documentation

📖 Core Documentation

Quick Start Guide - Get started in 5 minutes
Complete README - Full library documentation
API Reference - Detailed API docs
Usage Guide - Comprehensive examples

🤖 AI Assistant Integration

AI Assistant Docs (src/app/docs/ai-assistant): Ready-to-use prompts for tools like ChatGPT, Claude, or Copilot to generate Angular examples using @elm/ngx-animations.
Use with any LLM: Describe the motion you want (fade on scroll, bounce + rotate, performance tips, interaction-driven slides), then paste one of the provided prompts to get tailored code.

🚀 Publishing & Development

Publishing Guide - How to publish to NPM
Changelog - Version history

💡 Examples

Hero Section Animation

<ngx-stagger-list animation="slide-up" [staggerDelay]="150">
  <h1 class="hero-title">Welcome to Our Site</h1>
  <p class="hero-subtitle">Next-level animations</p>
  <button class="hero-cta">Get Started</button>
</ngx-stagger-list>

Card Grid with Scroll Reveal

@for (card of cards; track card.id) {
  <ngx-scroll-reveal animation="scale" [delay]="$index * 50">
    <div class="card">
      <h3>{{ card.title }}</h3>
      <p>{{ card.content }}</p>
    </div>
  </ngx-scroll-reveal>
}

Typewriter Effect (with RTL Support)

<!-- English -->
<ngx-typewriter 
  [text]="'Welcome to next-level animations!'"
  [speed]="50"
  [showCursor]="true">
</ngx-typewriter>

<!-- Arabic (RTL) -->
<ngx-typewriter 
  [text]="'مرحبا بكم في مكتبة الرسوم المتحركة'"
  [rtl]="true"
  [speed]="50">
</ngx-typewriter>

Timeline Animation (GSAP-like)

import { Component, inject, viewChild, ElementRef } from '@angular/core';
import { TimelineService } from '@elm/ngx-animations';

@Component({
  template: `
    <div #box1>Box 1</div>
    <div #box2>Box 2</div>
    <div #box3>Box 3</div>
  `
})
export class AnimationDemo {
  private timeline = inject(TimelineService);
  private box1 = viewChild<ElementRef>('box1');
  private box2 = viewChild<ElementRef>('box2');
  private box3 = viewChild<ElementRef>('box3');

  ngAfterViewInit() {
    const tl = this.timeline.create({ repeat: true });
    
    tl.to(this.box1()!, { opacity: '1', transform: 'translateX(100px)' }, 500)
      .to(this.box2()!, { opacity: '1', transform: 'scale(1.5)' }, 300)
      .parallel((ptl) => {
        ptl.to(this.box2()!, { transform: 'rotate(45deg)' }, 400);
        ptl.to(this.box3()!, { opacity: '1' }, 400);
      })
      .play();
  }
}

🎬 Demo Application

This project includes a comprehensive demo application showcasing all components and directives.

Live Demo: ngx-animations on Vercel

Run the Demo

# Install dependencies
npm install

# Serve the demo app
npm start

# Open browser to http://localhost:4200

The demo application includes:

✅ All 11 animation components/directives
✅ RTL examples (Arabic/Hebrew)
✅ Timeline demonstrations
✅ Interactive examples
✅ Performance best practices

🛠️ Development

Build the Library

# Development build
npm run build:lib:dev

# Production build
npm run build:lib

# Watch mode
npm run watch:lib

Test Locally

# Build and pack
npm run build:lib
npm run pack:lib

# Install in another project
npm install /path/to/elm-ngx-animations-1.0.0.tgz

Publish to NPM

# Dry run (test without publishing)
npm run publish:lib:dry

# Actual publish
npm run publish:lib

See Publishing Guide for detailed instructions.

🌍 RTL Support

All components fully support RTL layouts for Arabic, Hebrew, and other right-to-left languages.

Automatic Detection

<div dir="rtl">
  <div ngxSlideIn direction="left">
    <!-- Automatically adjusts for RTL -->
    محتوى عربي
  </div>
</div>

Explicit RTL

<div ngxSlideIn direction="left" [rtl]="true">
  Forces RTL behavior
</div>

♿ Accessibility

Respecting User Preferences

@Component({
  template: `
    <div ngxFadeIn [duration]="animationDuration">
      Content
    </div>
  `
})
export class MyComponent {
  animationDuration = window.matchMedia('(prefers-reduced-motion: reduce)').matches 
    ? 0 
    : 600;
}

📊 Performance Tips

Use triggerOnScroll for below-the-fold content
Prefer transform and opacity over other CSS properties
Use will-change CSS property for complex animations
Adjust threshold for intersection observer optimization

<div ngxFadeIn 
     [triggerOnScroll]="true" 
     [threshold]="0.5">
  Only animates when 50% visible
</div>

🗂️ Project Structure

animation-lib/
├── projects/
│   └── elm/
│       └── ngx-animations/          # Library source
│           ├── src/
│           │   ├── lib/
│           │   │   ├── directives/  # Animation directives
│           │   │   ├── components/  # Animation components
│           │   │   └── services/    # Timeline service
│           │   └── public-api.ts    # Public exports
│           ├── docs/                # Documentation
│           │   ├── API.md
│           │   ├── USAGE_GUIDE.md
│           │   └── PUBLISHING.md
│           ├── README.md
│           ├── CHANGELOG.md
│           └── package.json
├── src/
│   └── app/
│       └── demo/                    # Demo application
└── README.md                        # This file

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Guidelines

Follow the existing code style
Write tests for new features
Update documentation
Add examples to demo app

📄 License

See LICENSE for details.

🙏 Acknowledgments

Inspired by:

GSAP - For animation API patterns
Framer Motion - For modern animation concepts
Angular Community - For continuous support

📞 Support

🗺️ Roadmap

⭐ Show Your Support

If you find this library helpful, please consider:

⭐ Starring the repository
🐦 Sharing on social media
📝 Writing a blog post
🤝 Contributing to the project

Made with ❤️ for the ELM Angular community

Quick Start • Full Docs • API Reference • Publish Guide

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.vscode		.vscode
projects/elm/ngx-animations		projects/elm/ngx-animations
public		public
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
.postcssrc.json		.postcssrc.json
HOW_TO_USE.md		HOW_TO_USE.md
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
RENAME_INSTRUCTIONS.md		RENAME_INSTRUCTIONS.md
START_HERE.md		START_HERE.md
angular.json		angular.json
dummy		dummy
package-lock.json		package-lock.json
package.json		package.json
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.spec.json		tsconfig.spec.json

bananalasmari/ngx-animations

Folders and files

Latest commit

History

Repository files navigation