@impactdk/ngx-animate-in

ngx-animate-in

A directive to easily add animations to an element as it enters the viewport.

Example

Versions

• Angular 8+ - Use ^2.0.0
• Angular versions lower than 8 - Use ^1.0.0

Installation

npm install --save @impactdk/ngx-animate-in

Import the NgxLazyloadModule from @impactdk/ngx-animate-in in the module you want to use the directive in. If you wish you can add configs in the forRoot method on the module.

import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
import { BrowserModule } from '@angular/platform-browser';

import { NgxAnimateInModule } from '@impactdk/ngx-animate-in';

@NgModule({
    imports: [BrowserModule, NgxAnimateInModule],
    declarations: [AppComponent],
    bootstrap: [AppComponent],
    providers: [],
})
export class AppModule {}

Usage

To use the directive, import the NgxAnimateInModule in the module you want to use it in. Then add the directive selector NgxAnimateIn to the element you want to animate in.

<div class="greetings center">
  <div>
    <h1 NgxAnimateIn>{{'Hello from App Component'}}</h1>
  </div>
</div>

If you dont specify your own animation it will fall back to using the default animation which is a slideup-fadein animation.

Using your own animations

You can also specify your own animation by passing in an animation array in the "NgxAnimateInAnimation" attribute on your elements.

It expects one or more animations of the type AnimationMetadata so you can build it just like you would with any Angular animation.

import { Component, ViewEncapsulation, ViewChild } from '@angular/core';
import { animate, style } from '@angular/animations';

@Component({
    selector: 'app-root',
    template: `<div class="greetings center">
    <div>
      <h1 NgxAnimateIn>{{'Hello from App Component'}}</h1>
      <h2 NgxAnimateIn [NgxAnimateInAnimation]="customAnimation">Custom animation!</h2>
    </div>
  </div>
  `,
    styleUrls: ['./app.component.scss'],
    encapsulation: ViewEncapsulation.None,
})
export class AppComponent {
    customAnimation = [
        style({ opacity: 0, transform: 'rotate(355deg)' }),
        animate(
            '600ms cubic-bezier(0.35, 0, 0.25, 1)',
            style({ opacity: 1, transform: 'rotate(0deg)' })
        ),
    ];
}

Changing the default config

By default the root element of which we detect the intersection is the viewport. We also have a threshold of 10% meaning that the animation will not trigger until the element has 10% of its body within the viewport. It's also possible to define an offset of when the animation should start. For example, if you want it to trigger when it's 100px before the viewport. By default this is 0px.

The option type looks like this:

interface ObserverServiceConfig {
    root?: Element | null;
    rootMargin?: string;
    threshold?: number | number[];
}

root: The element that is used as the viewport for checking visiblity of the target. Must be the ancestor of the target. Defaults to the browser viewport if not specified or if null.

rootMargin: Margin around the root. Can have values similar to the CSS margin property, e.g. "10px 20px 30px 40px" (top, right, bottom, left). If the root element is specified, the values can be percentages. This set of values serves to grow or shrink each side of the root element's bounding box before computing intersections. Defaults to all zeros.

threshold: Either a single number or an array of numbers which indicate at what percentage of the target's visibility the observer's callback should be executed. If you only want to detect when visibility passes the 50% mark, you can use a value of 0.5. If you want the callback run every time visibility passes another 25%, you would specify the array [0, 0.25, 0.5, 0.75, 1]. The default is 0 (meaning as soon as even one pixel is visible, the callback will be run). A value of 1.0 means that the threshold isn't considered passed until every pixel is visible.

To override the defaults, simply pass a new config object into the forRoot function on the module like this:

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';

import { NgxAnimateInModule } from '@impactdk/ngx-animate-in';

import { AppComponent } from './app.component';

@NgModule({
    imports: [
        BrowserModule,
        BrowserAnimationsModule,
        NgxAnimateInModule.forRoot({
            threshold: 0,
            rootMargin: '-100px',
        }),
    ],
    declarations: [AppComponent],
    providers: [],
    bootstrap: [AppComponent],
})
export class AppModule {}

You only need to define the options you want changed, the rest will fall back to its defaults.

Browser support

The directive uses the experimental Intersection Observer API. Because of this, it's only supported in evergreen browsers, meaning anything but IE pretty much.

Check the Browser compatibility table carefully before using this in production.

Polyfill

It is possible to polyfill the Intersection Observer in older browsers.

There are several solutions I do however suggest you use this, made by google.

Installing the polyfill:

npm install intersection-observer

Then import it in your polyfills.ts if you're using Angular CLI. If you aren't, simply add it to one of your top level ts files such as main.ts like this:

import 'intersection-observer';

Further help

Reach out to MHO (Martin Hobert)