ASA - Angular Scroll Animations

Versatile library to easily animate elements as user scrolls down the page.

Installation

• With NPM:

npm install @penguin32/asa --save

• With Yarn:

yarn add @penguin32/asa

in your Angular project.

Usage

• Import the AsaModule and BrowserAnimationsModule/NoopAnimationsModule into the module wherever you want to use it:

import {AsaModule} from '@penguin32/asa';
import {BrowserAnimationsModule} from "@angular/platform-browser/animations";

@NgModule({
  imports: [
    // ...
    AsaModule,
    BrowserAnimationsModule,
  ]
})
export class AppModule {
}

Using included animations

This library comes with a handful of animations included. You can use them by passing the name of the animation as a string parameter to the [scrollAnimation] directive. The full list of available animations is available later in this document.

• Add the [scrollAnimation] directive to the element you want to animate:

<div [scrollAnimation]="'fadeInLeft'">
  <h1> When user scrolls to this currently invisible element </h1>
  <p> it will fade in and make it's entry to the page! </p>
</div>

Using custom animations

You can also create your own animations and use them with this library. To do so, you need to create field in your component that will hold the animation configuration as a AnimationMetadata[] object. You can then pass this field to the [scrollAnimation] directive.

• Create a field in your component that will hold the animation configuration:

import {animate, AnimationMetadata, keyframes, query, style} from "@angular/animations";

const customAnimationExample: AnimationMetadata[] = [
  query('*', [
    animate('500ms ease-out',
      keyframes([
        style({opacity: 0, transform: 'translateX(-100%)', offset: 0}),
        style({opacity: 1, transform: 'translateX(0)', offset: 1}),
      ]),
    ),
  ])
];

• Add the [scrollAnimation] directive to the element you want to animate:

<div [scrollAnimation]="customAnimationExample">
  <h1> Custom Animation example </h1>
  <p> This is a very cool way to animate-in a element into the page! </p>
</div>

Bind animation progress to scroll position

You can also bind the animation progress to the scroll position. This is a cool way to animate-in and out elements as user scrolls up and down the page.

• Add the [progressBoundToScroll] input to the element you want to animate:

<div [scrollAnimation]="'fadeInLeft'" [progressBoundToScroll]="true">
  <h1> This element will animate-in and out as user scrolls up and down the page </h1>
  <p> This is awesome! </p>
</div>

If [progressBoundToScroll] is set to false, the animation will be triggered only once and will not be triggered again as user scrolls up and down the page, and the element will stay visible once animated.

If the [progressBouldToScroll] is set to true, both [animationStart] and [animationEnd] will be used, as the animation is bound to the scroll position. On the other hand, if it's set to false, only [animationStart] will be used, as the animation will be triggered when the element is animationStart pixels from the bottom of the page.

Available settings

Directive	Type	Required	Default	Description
[scrollAnimation]	string AnimationMetadata[]	Yes	undefined	Name of the included animation to use or custom Angular animation.
[progressBoundToScroll]	boolean	No	false	If set to true, the animation progress (0 - 100%) will be bound to the scroll position ([animationStart] - [animationEnd]), otherwise the animation will trigger only once on [animationStart]
[animationStart]	number	No	200	Distance from the bottom of the page when the animation should trigger.
[animationEnd]	number	No	220	Distance from the bottom of the page when the animation should end. Used only when [progessBoundToScroll] is true.
[duration]	string	No	'500ms'	Duration of the animation in CSS time.
[curve]	string	No	'ease-out'	CSS curve of the animation to be used

Included animations

Fade

• fadeIn
• fadeInLeft
• fadeInRight
• fadeInTop
• fadeInBottom

Flip

• flipLeft
• flipRight
• flipTop
• flipBottom

Zoom

• zoomIn
• zoomOut

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please check CONTRIBUTING.md for more details.