ngx-page-scroll

ngx-page-scroll

Animated scrolling functionality for angular written in pure typescript with no additional dependencies

Features

• easy-to-use directive: scroll to an element referenced in the href-attribute (href="#mytarget) just by adding pageScroll directive
• service usage: trigger scroll animations from your component or when server responds
• customizable: adjust duration, offset or whether scrolling stops if the user interrupts (read more)
• use custom easing functions to calculate the scroll position over time
• works across routes (scrolls to target element as soon as the routing has finished) and in both directions (horizontal/vertical)

Table of contents

• Setup
• Usage
  • Directive
  • Service
• Configuration
• Directive API
• Example app

Setup

First you need to install the npm module:

npm install ngx-page-scroll --save

Then add the NgxPageScrollModule to the imports array of your application module:

import {NgxPageScrollModule} from 'ngx-page-scroll';

@NgModule({
    imports: [
        /* Other imports here */
        NgxPageScrollModule
        ]
})
export class AppModule {
}

To ensure there's only one instance of a PageScrollService (Singleton) it is recommended to add the PageScrollService to only one Injector, preferably the root injector of the application. You may read more about angular dependency injection hierarchy at their documentation.

Finally you need to specify how your application should load the ngx-page-scroll library:

Angular modules

All the compiled JavaScript files use ES2015 module format, so they are ready for usage with RollupJS. However, you cannot use them with SystemJS.

.metadata.json files are generated for usage with Angular AoT compiler.

SystemJS

UMD bundles are available for SystemJS loading. Example:

System.config({
    paths: {
        'npm:': 'node_modules/'
    },
    map: {
        app: 'app',

        '@angular/core'   : 'npm:@angular/core/bundles/core.umd.js',
        '@angular/common' : 'npm:@angular/common/bundles/common.umd.js',
        // further angular bundles...

        'ngx-page-scroll': 'npm:ngx-page-scroll/bundles/ngx-page-scroll.umd.js',

        rxjs: 'npm:rxjs',
    },
    packages: {
        app : {defaultExtension: 'js', main: './main.js'},
        rxjs: {defaultExtension: 'js'}
    }
});

Usage

Directive

In your template you may add the pageScroll attribute to elements with an href attribute pointing towards an id on the same page (e.g. #theId). The onClick event will be interrupted and the scroll animation starts. Alternatively you may set the optional pageScrollTarget property to a valid css selector to specify the target element to scroll to.

@Component({
   ...
   template: `...
        <a pageScroll href="#awesomePart">Take me to the awesomeness</a>
        <!-- Further content here -->
        <h2 id="awesomePart">This is where the awesome happens</h2>
   ...`,
})
export class MyComponent {
}

Service

You may use the service for more advanced scroll animations. Using the service you may trigger scroll animations on any custom event or more complex configuration. Possible use cases are server responses or after content initialization.

Start by obtaining a reference to the PageScrollService instance by adding it to your component's constructor. The PageScrollService offers a start() method to trigger PageScrollInstances. A PageScrollInstance is an object encapsulating all information relevant for performing a scroll animation. You may create a new PageScrollInstance by using the provided factory methods PageScrollInstance#simpleInstance and PageScrollInstance#newInstance.

import { Component, Inject, ViewChild, ElementRef } from '@angular/core';
import { DOCUMENT} from '@angular/common';
import { PageScrollConfig, PageScrollService, PageScrollInstance } from 'ngx-page-scroll';

@Component({
    template: `
        <p>Main content</p>
        <!-- Further content here -->
        <h2 id="head2">Part in a container</h2>
        <div #container>
            <p>Container content</p>
            <h3 id="head3">Heading</h3>
        </div>`
})
export class MyComponent {

     @ViewChild('container')
     private container: ElementRef;

     constructor(private pageScrollService: PageScrollService, @Inject(DOCUMENT) private document: any) {
     }

     public goToHead2(): void {
         let pageScrollInstance: PageScrollInstance = PageScrollInstance.simpleInstance(this.document, '#head2');
         this.pageScrollService.start(pageScrollInstance);
     };    
     
     public scrollSomewhereHorizontally(): void {
         let pageScrollInstance: PageScrollInstance = PageScrollInstance.newInstance({document: this.document, scrollTarget: '#targetToTheRight', verticalScrolling: false});
         this.pageScrollService.start(pageScrollInstance);
     }; 

     public goToHeadingInContainer(): void {
         let pageScrollInstance: PageScrollInstance = PageScrollInstance.newInstance({document: this.document, scrollTarget: '.headingClass', scrollingViews: [this.container.nativeElement]});
         this.pageScrollService.start(pageScrollInstance);
     };
 }

The PageScrollInstance#newInstance method takes a PageScrollOptions object. Most attributes are the same as attributes for the directive. Refer to the sources for a detailed list of options.

Configuration

The class PageScrollConfig offers static properties to be manipulated to configure the default behavior. Override the respective properties to change all page scroll-animation defaults.

Configuration Option	Type	Default	Description
defaultScrollOffset	number	0	Pixels to offset from the top of the element when scrolling to (positive value = scrolling will stop given pixels atop the target element).
defaultIsVerticalScrolling	boolean	true	Whether the scroll should happen to the target element in vertical direction (true, default) or horizontal (false)
defaultDuration	number	1250	Duration in milliseconds the whole scroll-animation should last.
defaultInterruptible	boolean	true	Whether the scroll animation should stop if the user interferes with it (true) or not (false).
defaultEasingLogic	EasingLogic	linearEasing	Easing method to be used while calculating the scroll position over time (default is linear easing).

Example

import {PageScrollConfig} from 'ngx-page-scroll';

export class AppComponent {
    constructor() {
        PageScrollConfig.defaultScrollOffset = 50;
        PageScrollConfig.defaultEasingLogic = {
            ease: (t: number, b: number, c: number, d: number): number => {
                // easeInOutExpo easing
                if (t === 0) return b;
                if (t === d) return b + c;
                if ((t /= d / 2) < 1) return c / 2 * Math.pow(2, 10 * (t - 1)) + b;
                return c / 2 * (-Math.pow(2, -10 * --t) + 2) + b;
            }
        };
    }
}

Directive API

Additional attributes may be set on an DOM element using the pageScroll directive for customization. They take precedence over the default settings specified in PageScrollConfig class. Thereby it is possible to have all page scroll-animations last e.g. 2 seconds, but a specific one should be performed with a custom easing function and a duration of only 1 second.

PageScroll properties

Attribute	Type	Default	Description
pageScroll			Attribute adding scroll-animation behavior when the click-event happens on the element.
pageScrollTarget	string		Optional attribute to set the element that should be scrolled to. Takes precedence over the ´href´-value
pageScrollHorizontal	boolean	false	Whether the scroll should happen in vertical direction (false, default) or horizontal (true).
pageScrollOffset	number	0	Pixels to offset from the top of the element when scrolling to (positive value = scrolling will stop given pixels atop the target element).
pageScrollDuration	number	1250	Duration in milliseconds the whole scroll-animation should last.
pageScrollSpeed	number	-	Speed in Pixel/Second the animation should take. Only applied if no duration is set.
pageScrollInterruptible	boolean	true	Whether the scroll animation should stop if the user interferes with it (true) or not (false).
pageScrollAdjustHash	boolean	false	Whether the routes hash/fragment should be updated to reflect to section that has been scrolled to
pageScrollEasing	EasingLogic	linearEasing	Easing method to be used while calculating the scroll position over time (default is linear easing).

PageScroll events

Event	Type	Description
pageScrollFinish	boolean	Fired when the scroll-animation stops. Emits a boolean value which indicates whether the scroll animation finished successfully and reached its target (true) or not (false). Possible reasons for false: target not found or interrupted due to another scroll animation starting or user interaction.

Example

The following example will check whether the route Home is currently loaded. If this is true, the scroll-animation will be performed with the default properties. If a different route is loaded, a subscription for route changes will be made and the scroll-animation will be performed as soon as the new route is loaded.

 <a pageScroll [routerLink]="['Home']" href="#myanchor">Go there</a>

Overriding all possible properties. doSmth() and myEasing are defined in the component

 <a pageScroll [pageScrollOffset]="0" [pageScrollDuration]="2000" [pageScrollEasing]="myEasing" [pageScrollInterruptible]="false" (pageScrollFinish)="doSmth($event)" href="#theanchor">Visit</a>

    myEasing: EasingLogic = {
        ease: (t: number, b: number, c: number, d: number): number => {
            // easeInOutExpo easing
            if (t === 0) return b;
            if (t === d) return b + c;
            if ((t /= d / 2) < 1) return c / 2 * Math.pow(2, 10 * (t - 1)) + b;
            return c / 2 * (-Math.pow(2, -10 * --t) + 2) + b;
        }
    };

    doSmth(reachedTarget: boolean): void {
        if (reachedTarget) {
            console.log('Yeah, we reached our destination');
        } else {
            console.log('Ohoh, something interrupted us');
        }
    }

Example App

The demo subfolder contains a project created with angular-cli that has been adapted to showcase the functionality of ngx-page-scroll. Run the demo app by checking out that repository and execute the following command in the project root directory:

npm run demo

This will perform the following steps:

• Install the dependencies of the ngx-page-scroll project
• Install the dependencies of the demo-app project
• Replace the ngx-page-scroll library in the demo-app with a fresh build
• Run the demo server (ng serve)

TODO:

• Test across more different browsers

License

MIT

Changelog

5.0.1 (2018-11-30)

Other

• Add angular 7 to supported version range (#329)