THIS IS A FORK FOR @nicky-lenaers/ngx-scroll-to (I release for most updated angular version only)
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.
```
## 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**
```typescript
import { Injectable } from "@angular/core";
import {
ScrollToService,
ScrollToConfigOptions,
} from "@nicky-lenaers/ngx-scroll-to";
@Injectable()
export class MyService {
constructor(private scrollToService: ScrollToService) {}
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**
```typescript
import { Injectable } from "@angular/core";
import {
ScrollToService,
ScrollToConfigOptions,
} from "@nicky-lenaers/ngx-scroll-to";
@Injectable()
export class MyService {
constructor(private scrollToService: ScrollToService) {}
triggerScrollToOffsetOnly(offset: number = 0) {
const config: ScrollToConfigOptions = {
offset,
};
this.scrollToService.scrollTo(config);
}
}
```
## Advanced Usage - Directive
**my.component.ts**
```typescript
import {
ScrollToAnimationEasing,
ScrollToEvent,
ScrollToOffsetMap,
} from "@nicky-lenaers/ngx-scroll-to";
@Component({
selector: "my-component",
templateUrl: "./my.component.html",
})
export class MyComponent {
ngxScrollToDestination: string;
ngxScrollToEvent: ScrollToEvent;
ngxScrollToDuration: number;
ngxScrollToEasing: ScrollToAnimationEasing;
ngxScrollToOffset: number;
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);
}
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**
```typescript
import { Injectable } from "@angular/core";
import {
ScrollToService,
ScrollToConfigOptions,
} from "@nicky-lenaers/ngx-scroll-to";
@Injectable()
export class MyService {
constructor(private scrollToService: ScrollToService) {}
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, `ngxScrollTo` 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**
```typescript
import { Injectable } from "@angular/core";
import { ScrollToService } from "@nicky-lenaers/ngx-scroll-to";
@Injectable()
export class FaultyService {
constructor(private scrollToService: ScrollToService) {}
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
#### `[ngxScrollTo]`
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.
#### `[ngxScrollToEvent]`
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`
#### `[ngxScrollToDuration]`
This value controls to duration of your scroll animation. Note that this value is in milliseconds.
#### `[ngxScrollToEasing]`
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`
#### `[ngxScrollToOffset]`
This value controls the offset with respect to the top of the destination HTML element. Note that this value is in pixels.
#### `[ngxScrollToOffsetMap]`
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)
