Skip to content
Scroll to any element to enhance scroll-based features in you app. Works for Angular 4+, both AoT and SSR. No dependencies.
TypeScript HTML JavaScript CSS
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci ci(node): upgrade node and npm versions (#127) Jan 9, 2020
.github feat: github contributing guidelines and code of conduct (#85) May 10, 2018
e2e
projects/ngx-scroll-to fix: scroll to element with relative positioned parent (#124) Jan 9, 2020
src feat(lib): support for angular v7 (#114) Dec 12, 2018
.editorconfig Repo Upgrade Oct 4, 2017
.gitignore feat: passive events (#99) Sep 11, 2018
.huskyrc.json feat(lib): support for angular v7 (#114) Dec 12, 2018
.npmrc Minor Changes Oct 4, 2017
CHANGELOG.md build: update to v3.0.0 Aug 13, 2019
LICENSE Add LICENSE & Update GitHub Release Script Oct 4, 2017
README.md update readme Jan 9, 2020
angular.json feat(lib): support for angular v7 (#114) Dec 12, 2018
karma.conf.js fix(module): Correctly calcuate `ngx-scroll-to-offset` value on inver… Oct 5, 2017
package-lock.json fix: incorrect package version Aug 13, 2019
package.json ci(node): upgrade node and npm versions (#127) Jan 9, 2020
tsconfig.json feat(lib): support for angular v7 (#114) Dec 12, 2018
tslint.json chore(package): don't enforce newer node engines (#118) Jun 6, 2019

README.md

This project is no longer maintained.




ngx-scroll-to

A simple Angular 4+ plugin enabling you to smooth scroll to any element on your page and enhance scroll-based features in your app. Works for Angular 4+, both AoT and SSR. No dependencies.

Support for Angular 8!

Subject Type Badge
CI / CD Circle CI Circle CI
Releases GitHub GitHub Release
  NPM NPM Release
Dependencies Production Production Dependencies
  Peer Peer Dependencies
  Development Development Dependencies
  Optional Optional Dependencies
Downloads NPM NPM Monthly Downloads
License MIT License

Current Angular Version

npm version

Installation

Angular 8

$ npm install @nicky-lenaers/ngx-scroll-to

Angular 7

$ npm install @nicky-lenaers/ngx-scroll-to@'2'

Angular 6

$ npm install @nicky-lenaers/ngx-scroll-to@'1'

Angular <= 5.x

$ npm install @nicky-lenaers/ngx-scroll-to@'<1'

Setup

...
import { ScrollToModule } from '@nicky-lenaers/ngx-scroll-to';
...

@NgModule({
  imports: [
    ...
    ScrollToModule.forRoot()
  ],
  ...
  bootstrap: [AppComponent]
})
export class AppModule { }

Basic Usage - Directive to Target

my.component.html

<!-- Works for including '#' -->
<button [ngx-scroll-to]="'#destination'">Go to destination</button>

<!-- Works for excluding '#' -->
<button [ngx-scroll-to]="'destination'">Go to destination</button>

<!-- Works for Angular ElementRef -->
<button [ngx-scroll-to]="destinationRef">Go to destination</button>

<div id="destination" #destinationRef>
  You've reached your destination.
</div>

Basic Usage - Directive to Offset Only

Besides scrolling to a specific element, it is also possible to scroll a given offset only. This can be achieved by an empty target and an offset:

my.component.html

<button 
  ngx-scroll-to 
  [ngx-scroll-to-offset]="200">
  Go down 200 pixels
</button>

Basic Usage - Service to Target

my.component.html

<button (click)="triggerScrollTo()">Go to destination</button>

<div id="destination">
  You've reached your destination.
</div>

my.service.ts

import { Injectable } from '@angular/core';
import { ScrollToService, ScrollToConfigOptions } from '@nicky-lenaers/ngx-scroll-to';

@Injectable()
export class MyService {

  constructor(private _scrollToService: ScrollToService) { }

  public triggerScrollTo() {
    
    const config: ScrollToConfigOptions = {
      target: 'destination'
    };

    this._scrollToService.scrollTo(config);
  }
}

Basic Usage - Service to Offset Only

Just like with the Directive, the Service can be used to scroll to an offset only instead of a given target element:

my.component.html

<button (click)="triggerScrollToOffsetOnly(200)">Go down 200 pixels</button>

my.service.ts

import { Injectable } from '@angular/core';
import { ScrollToService, ScrollToConfigOptions } from '@nicky-lenaers/ngx-scroll-to';

@Injectable()
export class MyService {

  constructor(private _scrollToService: ScrollToService) { }

  public triggerScrollToOffsetOnly(offset: number = 0) {
    
    const config: ScrollToConfigOptions = {
      offset
    };

    this._scrollToService.scrollTo(config);
  }
}

Advanced Usage - Directive

my.component.ts

import { ScrollToAnimationEasing, ScrollToEvent, ScrollToOffsetMap } from '@nicky-lenaers/ngx-scroll-to';

@Component({
  selector: 'my-component'
  templateUrl: './my.component.html'
})
export class MyComponent {

  public ngxScrollToDestination: string;
  public ngxScrollToEvent: ScrollToEvent;
  public ngxScrollToDuration: number;
  public ngxScrollToEasing: ScrollToAnimationEasing;
  public ngxScrollToOffset: number;
  public ngxScrollToOffsetMap: ScrollToOffsetMap;

  constructor() {

    this.ngxScrollToDestination = 'destination-1';
    this.ngxScrollToEvent = 'mouseenter';
    this.ngxScrollToDuration = 1500;
    this.ngxScrollToEasing = 'easeOutElastic';
    this.ngxScrollToOffset = 300;
    this.ngxScrollToOffsetMap = new Map();
    this.ngxScrollToOffsetMap
      .set(480, 100)
      .set(768, 200)
      .set(1240, 300)
      .set(1920, 400)

  }

  public toggleDestination() {
    this.ngxScrollToDestination = this.ngxScrollToDestination === 'destination-1' ? 'destination-2' : 'destination-1';
  }
}

my.component.html

<button (click)="toggleDestination()">Toggle Destination</button>

<button 
  [ngx-scroll-to]="ngxScrollToDestination"
  [ngx-scroll-to-event]="ngxScrollToEvent"
  [ngx-scroll-to-duration]="ngxScrollToDuration"
  [ngx-scroll-to-easing]="ngxScrollToEasing"
  [ngx-scroll-to-offset]="ngxScrollToOffset"
  [ngx-scroll-to-offset-map]="ngxScrollToOffsetMap">
  Go to destination
</button>

<div id="destination-1">
  You've reached your first destination
</div>

<div id="destination-2">
  You've reached your second destination
</div>

Advanced Usage - Service

my.component.html

<button (click)="triggerScrollTo()">Go to destination</button>

<div id="custom-container">
  <div id="destination">
    You've reached your destination.
  </div>
</div>

my.service.ts

import { Injectable } from '@angular/core';
import { ScrollToService, ScrollToConfigOptions } from '@nicky-lenaers/ngx-scroll-to';

@Injectable()
export class MyService {

  constructor(private _scrollToService: ScrollToService) { }

  public triggerScrollTo() {
    
    /**
     * @see NOTE:1
     */
    const config: ScrollToConfigOptions = {
      container: 'custom-container',
      target: 'destination',
      duration: 650,
      easing: 'easeOutElastic',
      offset: 20
    };

    this._scrollToService.scrollTo(config);
  }
}

NOTE:1

The container property is an optional property. By default, ngx-scroll-to searches for the first scrollable parent HTMLElement with respect to the specified target. This should suffice in most cases. However, if multiple scrollable parents reside in the DOM tree, you have the degree of freedom the specify a specific container by using the container property, as used in the above example.

Directive Attributes Map

Options Type Default
ngx-scroll-to string | number | ElementRef | HTMLElement ''
ngx-scroll-to-event ScrollToEvent click
ngx-scroll-to-duration number 650
ngx-scroll-to-easing ScrollToAnimationEasing easeInOutQuad
ngx-scroll-to-offset number 0
ngx-scroll-to-offset-map ScrollToOffsetMap new Map()

Error Handling

In some occasions, one might misspell a target or container selector string. Even though ngx-scoll-to will not be able to initiate the scrolling animation, you can catch the internally generated error and handle it as you please on the Observable chain returned from the scrollTo method.

faulty.service.ts

import { Injectable } from '@angular/core';
import { ScrollToService } from '@nicky-lenaers/ngx-scroll-to';

@Injectable()
export class FaultyService {

  constructor(private _scrollToService: ScrollToService) { }

  public triggerScrollTo() {
    
    this._scrollToService
      .scrollTo({
        target: 'faulty-id'
      })
      .subscribe(
        value => { console.log(value) },
        err => console.error(err) // Error is caught and logged instead of thrown
      );
  }
}

Directive Attribute Map Details

[ngx-scroll-to]

This value specifies the ID of the HTML Element to scroll to. Note the outer double quotes "" and the inner single quotes '' in the above example(s). This enables you to dynamically set the string value based on a class property of your Component.

[ngx-scroll-to-event]

This value controls to event on which to trigger the scroll animation. Allowed values are:

  • click
  • mouseenter
  • mouseover
  • mousedown
  • mouseup
  • dblclick
  • contextmenu
  • wheel
  • mouseleave
  • mouseout

[ngx-scroll-to-duration]

This value controls to duration of your scroll animation. Note that this value is in milliseconds.

[ngx-scroll-to-easing]

This value controls a named easing logic function to control your animation easing. Allowed values are:

  • easeInQuad
  • easeOutQuad
  • easeInOutQuad
  • easeInCubic
  • easeOutCubic
  • easeInOutCubic
  • easeInQuart
  • easeOutQuart
  • easeInOutQuart
  • easeInQuint
  • easeOutQuint
  • easeInOutQuint
  • easeOutElastic

[ngx-scroll-to-offset]

This value controls the offset with respect to the top of the destination HTML element. Note that this value is in pixels.

[ngx-scroll-to-offset-map]

This value allows you to control dynamic offsets based on the width of the device screen. The Map get's iterated over internally in a sequential fashion, meaning you need to supply key values in the order from low to high. The key of the Map defines the width treshold. The value of the Map defines the offset. Note that this value is in pixels.

Contributing

Please see Contributing Guidelines.

Code of Conduct

Please see Code of Conduct.

License

MIT

You can’t perform that action at this time.