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.
```
## 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**
```html
```
## Basic Usage - Service to Target
**my.component.html**
```html
You've reached your destination.
```
**my.service.ts**
```js
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**
```html
```
**my.service.ts**
```js
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**
```js
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**
```html
You've reached your first destination
You've reached your second destination
```
## Advanced Usage - Service
**my.component.html**
```html
You've reached your destination.
```
**my.service.ts**
```js
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
## 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**
```js
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](.github/CONTRIBUTING.md).
# Code of Conduct
Please see [Code of Conduct](.github/CODE_OF_CONDUCT.md).
# License
[MIT](/LICENSE)
