ng2-simple-page-scroll
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.0 • Public • Published

    npm version Code Climate MIT license Dependency Status devDependency Status

    ng2-simple-page-scroll

    Animated "scroll to element" functionality written in pure angular2 with no additional dependencies

    Features

    • easy-to-use directive: scroll to the top edge of an element referenced in the href-attribute (href="#mytarget) just by adding simplePageScroll directive
    • service usage: trigger instant scrolls from your component or when server responds
    • works across routes (scrolls to target element as soon as the routing has finished)

    Table of contents

    Setup

    First you need to install the npm module:

    npm install ng2-simple-page-scroll --save

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

    import {Ng2SimplePageScrollModule} from 'ng2-simple-page-scroll';
     
    @NgModule({
        imports: [
            /* Other imports here */
            Ng2SimplePageScrollModule.forRoot()
            ]
    })
    export class AppModule {
    }

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

    Angular2 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 Angular2 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...
     
            'ng2-simple-page-scroll/ng2-simple-page-scroll': 'npm:ng2-simple-page-scroll/bundles/ng2-simple-page-scroll.umd.js',
     
            rxjs: 'npm:rxjs',
        },
        packages: {
            app : {defaultExtension: 'js', main: './main.js'},
            rxjs: {defaultExtension: 'js'}
        }
    });
    import {Ng2SimplePageScrollModule} from 'ng2-simple-page-scroll/ng2-simple-page-scroll';
     
    @NgModule({
        imports: [
            /* Other imports here */
            Ng2SimplePageScrollModule.forRoot()
            ]
    })
    export class AppModule {
    }

    Usage

    Directive

    In your template you may add the simplePageScroll attribute to elements with an href attribute pointing towards an id on the same page (e.g. #theId).

     
    @Component({
       ...
       template: `...
            <a simplePageScroll 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 programmatic instant scrolls to HTML elements. Possible use cases are server responses or after content initialization.

    Start by obtaining a reference to the SimplePageScrollService instance by adding it to your component's constructor. The SimplePageScrollService offers a simple scrollToElement() function that accepts an element #id or a reference to an HTMLElement.

    @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 {
     
         constructor(private simplePageScrollService: SimplePageScrollService, @Inject(DOCUMENT) private document: Document) {
         }
     
         public goToHead2(): void {
             this.simplePageScrollService.scrollToElement("#head2", /* optional offset */);
             this.simplePageScrollService.scrollToElement(elementReference, /* optional offset */);
         };
     }

    Configuration

    The class SimplePageScrollConfig 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).

    Example

    import {SimplePageScrollConfig} from 'ng2-simple-page-scroll';
     
    export class AppComponent {
        constructor() {
            SimplePageScrollConfig.defaultScrollOffset = 50;
        }
    }

    Directive API

    Additional attributes may be set on an DOM element using the simplePageScroll directive for customization. They take precedence over the default settings specified in SimplePageScrollConfig class. Thereby it is possible to have all page scrolls have a default offset, but a specific one should have a different offset.

    PageScroll properties

    Attribute Type Default Description
    simplePageScroll Attribute adding scroll behavior when the click-event happens on the element.
    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).

    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 (true) or not (false). Possible reasons for false: target not found.

    Example

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

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

    Overriding all possible properties. doSmth() is defined in the component

     <a simplePageScroll [pageScrollOffset]="0" (pageScrollFinish)="doSmth($event)" href="#theanchor">Visit</a>
     
        doSmth(scrollSuccesful: boolean): void {
            if (scrollSuccesful) {
                console.log('Yeah, we scrolled');
            } else {
                console.log('Ohoh, something prevented the scroll');
            }
        }

    Install

    npm i ng2-simple-page-scroll

    DownloadsWeekly Downloads

    42

    Version

    2.0.0

    License

    MIT

    Last publish

    Collaborators

    • bbottema