Convenience directive for animated scrolling functionality for angular written in pure typescript
npm install ngx-page-scrollhref="#mytarget) just by adding pageScroll directive
sh
npm install ngx-page-scroll-core --save
`
Then add the NgxPageScrollModule to the imports array of your application module:
`typescript
import { NgxPageScrollCoreModule } from 'ngx-page-scroll-core';
@NgModule({
imports: [
/ Other imports here /
NgxPageScrollCoreModule
]
})
export class AppModule {
}
`
$3
Using the PageScrollService#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.
`typescript
import { Inject } from '@angular/core';
import { DOCUMENT } from '@angular/common';
import { PageScrollService } from 'ngx-page-scroll-core';
export class MyComponent {
constructor(private pageScrollService: PageScrollService, @Inject(DOCUMENT) private document: any) {
}
ngOnInit(): void {
this.pageScrollService.scroll({
document: this.document,
scrollTarget: '.theEnd',
});
}
}
`
Note: The scroll() method is a shorthand from creating a PageScrollInstance (an object encapsulating all information
relevant for performing a scroll animation) using PageScrollService#create and starting it using
the PageScrollService#start method.
$3
When importing the PageScrollCoreModule one can provide option overrides:
`typescript
imports: [
...
NgxPageScrollCoreModule.forRoot({duration: 2500, easingLogic: ...}),
]
`
Check the PageScrollConfig interface
for possible options and their impact. The default values may be found in the defaultPageScrollConfig)
object.
Directive
For ease of use a directive pageScroll exists, which allows you to quickly add scroll animations to your angular app by
adding a property to your existing HTML a-tags. It can also work cross-routes, meaning it will start the scroll animation
after the target route has been loaded.
It utilizes the ngx-page-scroll-core module for that, thus requires it as a peer dependency.
$3
First you need to install the directive npm module:
`sh
npm install ngx-page-scroll --save
`
Then add the NgxPageScrollModule to the imports array of your application module:
`typescript
import { NgxPageScrollModule } from 'ngx-page-scroll';
@NgModule({
imports: [
/ Other imports here /
NgxPageScrollModule
]
})
export class AppModule {
}
`
$3
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.
`typescript
@Component({
...
template: ...
,
})
export class MyComponent {
}
`
$3
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. |
| pageScrollInView | boolean | true | Whether the scroll animation should happen even when the scroll target is already inside the view port (true). Set to false to skip scroll animation if target is already in view. |
| 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.
`html
Go there
`
Overriding all possible properties. doSmth() and myEasing are
defined in the component
`html
Visit
`
`typescript
public myEasing: EasingLogic = (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');
}
}
``