Repository files navigation

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

• flexible: trigger scroll animations after component load, server response, etc.
• easy-to-use directive: scroll to an element referenced in the href-attribute(href="#mytarget) just by addingpageScroll directive
• 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 therouting has finished) and in both directions (horizontal/vertical)

• ngx-page-scroll
  • Features
  • Table of contents
    • Version compatibility
  • Service
    • Setup
    • Usage
    • Configuration
  • Directive
    • Setup
    • Usage
    • Directive API
      • PageScroll properties
      • PageScroll events
      • Example
  • FAQ and common problems
  • License

Install later versions in case your app is not running the very latest angular version.

First you need to install the core npm module:

npm install ngx-page-scroll-core --save

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

import{NgxPageScrollCoreModule}from'ngx-page-scroll-core';@NgModule({imports:[/* Other imports here */NgxPageScrollCoreModule]})exportclassAppModule{}

Using thePageScrollService#scroll method you may trigger scroll animations. Provide an options object that provides a reference to the document and the scroll target. Additional properties are optional.

import{Inject}from'@angular/core';import{DOCUMENT}from'@angular/common';import{PageScrollService}from'ngx-page-scroll-core';exportclassMyComponent{constructor(privatepageScrollService:PageScrollService, @Inject(DOCUMENT)privatedocument:any){}ngOnInit():void{this.pageScrollService.scroll({document:this.document,scrollTarget:'.theEnd',});}}

Note: Thescroll() method is a shorthand from creating aPageScrollInstance (an object encapsulating all informationrelevant for performing a scroll animation) usingPageScrollService#create and starting it usingthePageScrollService#start method.

When importing thePageScrollCoreModule one can provide option overrides:

imports:[  ...NgxPageScrollCoreModule.forRoot({duration:2500,easingLogic: ...}),]

Check thePageScrollConfig interfacefor possible options and their impact. The default values may be found in thedefaultPageScrollConfigobject.

For ease of use a directivepageScroll exists, which allows you to quickly add scroll animations to your angular app byadding a property to your existing HTML a-tags. It can also work cross-routes, meaning it will start the scroll animationafter the target route has been loaded.It utilizes the ngx-page-scroll-core module for that, thus requires it as a peer dependency.

First you need to install the directive npm module:

npm install ngx-page-scroll --save

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

import{NgxPageScrollModule}from'ngx-page-scroll';@NgModule({imports:[/* Other imports here */NgxPageScrollModule]})exportclassAppModule{}

In your template you may add thepageScroll attribute to elements with anhref attribute pointing towards an id onthe same page (e.g.#theId). TheonClick event will be interrupted and the scroll animation starts.Alternatively you may set the optionalpageScrollTarget property to a valid css selector to specify thetarget element to scroll to.

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

Additional attributes may be set on an DOM element using thepageScroll directive for customization.They take precedence over the default settings specified inPageScrollConfig class. Thereby it ispossible 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 durationof only 1 second.

The following example will check whether the routeHome is currently loaded.If this is true, the scroll-animation will be performed with the defaultproperties. If a different route is loaded, a subscription for route changeswill be made and the scroll-animation will be performed as soon as the newroute is loaded.

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

Overriding all possible properties.doSmth() andmyEasing aredefined in the component

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

public myEasing:EasingLogic=(t:number,b:number,c:number,d:number):number=>{// easeInOutExpo easingif(t===0){returnb;}if(t===d){returnb+c;}if((t/=d/2)<1){returnc/2*Math.pow(2,10*(t-1))+b;}returnc/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');}}

Please have a look at the wiki section of the GitHub repo athttps://github.com/Nolanus/ngx-page-scroll/wiki/FAQ for frequent questions and problems.

MIT