ui-essentials/projects/ui-animations/README.md

UI Animations

A comprehensive CSS animation library with Angular services and directives for programmatic control.

Features

• Pure CSS animations - Framework agnostic, works everywhere
• Angular integration - Services and directives for programmatic control
• Comprehensive collection - Entrance, exit, emphasis, and transition animations
• Design system integration - Uses semantic motion tokens for consistent timing and easing
• Utility classes - Animation timing, delays, and control utilities
• SCSS mixins - Create custom animations easily

Installation

npm install ui-animations

Usage

Import Styles

Add to your global styles or component styles:

// Complete animation library
@use 'ui-animations/src/styles' as animations;

// Or import specific modules
@use 'ui-animations/src/styles/animations/entrances';
@use 'ui-animations/src/styles/animations/emphasis';
@use 'ui-animations/src/styles/utilities/animation-utilities';

CSS Classes

Simply add animation classes to your HTML elements:

<!-- Entrance animations -->
<div class="animate-fade-in">Fade in animation</div>
<div class="animate-slide-in-up animation-delay-200">Delayed slide up</div>

<!-- Emphasis animations -->
<button class="animate-bounce">Bouncing button</button>
<div class="animate-pulse animation-infinite">Pulsing element</div>

<!-- Exit animations -->
<div class="animate-fade-out">Fade out animation</div>

Angular Service

import { UiAnimationsService } from 'ui-animations';

constructor(private animationService: UiAnimationsService) {}

// Animate an element
animateElement() {
  const element = document.getElementById('my-element');
  this.animationService.animateOnce(element, 'animate-bounce');
}

// Animate with callback
animateWithCallback() {
  const element = document.getElementById('my-element');
  this.animationService.animate(element, 'animate-fade-out', () => {
    console.log('Animation completed!');
  });
}

Angular Directive

import { AnimateDirective } from 'ui-animations';

@Component({
  imports: [AnimateDirective]
})

<!-- Immediate animation -->
<div uiAnimate="animate-fade-in-up">Auto animates on load</div>

<!-- Hover trigger -->
<div uiAnimate="animate-bounce" [animationTrigger]="'hover'">
  Hover to animate
</div>

<!-- Click trigger with single use -->
<button uiAnimate="animate-tada" [animationTrigger]="'click'" [animationOnce]="true">
  Click me!
</button>

Animation Categories

Entrances

• animate-fade-in - Basic fade in
• animate-fade-in-up/down/left/right - Fade with direction
• animate-slide-in-up/down - Slide animations
• animate-zoom-in - Scale up animation
• animate-rotate-in - Rotate entrance

Exits

• animate-fade-out - Basic fade out
• animate-fade-out-up/down/left/right - Fade with direction
• animate-slide-out-up/down - Slide animations
• animate-zoom-out - Scale down animation
• animate-rotate-out - Rotate exit

Emphasis

• animate-bounce - Bouncing effect
• animate-shake - Horizontal shake
• animate-pulse - Scaling pulse
• animate-wobble - Wobble motion
• animate-tada - Celebration animation
• animate-heartbeat - Heart beat effect

Utilities

• animation-delay-100/200/300/500/1000 - Animation delays
• animation-duration-fast/normal/slow/slower - Duration control
• animation-infinite/once/twice - Iteration control
• animation-paused/running - Playback control

SCSS Mixins

Create custom animations using provided mixins with semantic tokens:

@use 'ui-animations/src/styles/mixins/animation-mixins' as mixins;
@use 'ui-design-system/src/styles/semantic/motion' as motion;

.my-custom-animation {
  @include mixins.animate(myKeyframes, motion.$semantic-motion-duration-normal, motion.$semantic-motion-easing-ease-out);
}

.hover-effect {
  @include mixins.hover-animation(transform, scale(1.1), motion.$semantic-motion-duration-fast);
}

.loading-spinner {
  @include mixins.loading-animation(40px, #007bff);
}

Design System Integration

All animations now use semantic motion tokens from the design system:

• Durations: $semantic-motion-duration-fast, $semantic-motion-duration-normal, $semantic-motion-duration-slow, etc.
• Easing: $semantic-motion-easing-ease-out, $semantic-motion-easing-spring, $semantic-motion-easing-bounce, etc.
• Spacing: Animation distances use semantic spacing tokens for consistency
• Timing: Delays use semantic transition timing tokens

This ensures animations are consistent with your design system's motion principles.

Demo

Visit the demo application to see all animations in action and experiment with different options.