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.
Subject | Type | Badge |
---|---|---|
CI / CD | Circle CI |
|
Releases | GitHub |
|
NPM |
|
|
Dependencies | Production |
|
Peer |
|
|
Development |
|
|
Optional |
|
|
Downloads | NPM |
|
License | MIT |
|
Current Angular Version
$ npm install @nicky-lenaers/ngx-scroll-to
...
import { ScrollToModule } from '@nicky-lenaers/ngx-scroll-to';
...
@NgModule({
imports: [
...
ScrollToModule.forRoot()
],
...
bootstrap: [AppComponent]
})
export class AppModule { }
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>
<div id="destination">
You've reached your destination.
</div>
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);
}
}
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>
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.
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() |
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.log(err) // Error is caught and logged instead of thrown
);
}
}
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.
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
This value controls to duration of your scroll animation. Note that this value is in milliseconds.
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
This value controls the offset with respect to the top of the destination HTML element. Note that this value is in pixels.
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.