Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nicky-lenaers/ngx-scroll-to
Scroll to any element to enhance scroll-based features in you app. Works for Angular 4+, both AoT and SSR. No dependencies.
https://github.com/nicky-lenaers/ngx-scroll-to
angular angular-aot angular-universal angular2 angular4 ngx ngx-scroll-to scroll scrolling smooth-scrolling
Last synced: 29 days ago
JSON representation
Scroll to any element to enhance scroll-based features in you app. Works for Angular 4+, both AoT and SSR. No dependencies.
- Host: GitHub
- URL: https://github.com/nicky-lenaers/ngx-scroll-to
- Owner: nicky-lenaers
- License: mit
- Created: 2017-07-13T08:31:15.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-05-23T13:31:01.000Z (over 1 year ago)
- Last Synced: 2024-09-28T17:04:14.621Z (about 1 month ago)
- Topics: angular, angular-aot, angular-universal, angular2, angular4, ngx, ngx-scroll-to, scroll, scrolling, smooth-scrolling
- Language: TypeScript
- Homepage:
- Size: 1.74 MB
- Stars: 276
- Watchers: 11
- Forks: 80
- Open Issues: 25
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
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 9!
Subject
Type
Badge
CI / CD
Circle CI
Releases
GitHub
NPM
Dependencies
Production
Peer
Development
Optional
Downloads
NPM
License
MIT
Current Angular Version
[](https://www.npmjs.com/~angular)
## Installation
Angular 14
```sh
$ npm install @nicky-lenaers/ngx-scroll-to
```
Angular 13
```sh
$ npm install @nicky-lenaers/ngx-scroll-to@'13'
```
Angular 8 and 9
```sh
$ npm install @nicky-lenaers/ngx-scroll-to@'9'
```
Angular 7
```sh
$ npm install @nicky-lenaers/ngx-scroll-to@'2'
```
Angular 6
```sh
$ npm install @nicky-lenaers/ngx-scroll-to@'1'
```
Angular <= 5.x
```sh
$ npm install @nicky-lenaers/ngx-scroll-to@'<1'
```
## Setup
```typescript
...
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**
```html
Go to destination
Go to destination
Go to destination
You've reached your destination.
```
## 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
Go down 200 pixels
```
## Basic Usage - Service to Target
**my.component.html**
```html
Go to destination
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
Go down 200 pixels
```
**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
Toggle Destination
Go to destination
You've reached your first destination
You've reached your second destination
```
## Advanced Usage - Service
**my.component.html**
```html
Go to destination
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
Options
Type
Default
ngxScrollTo
string | number | ElementRef | HTMLElement
''
ngxScrollToEvent
ScrollToEvent
click
ngxScrollToDuration
number
650
ngxScrollToEasing
ScrollToAnimationEasing
easeInOutQuad
ngxScrollToOffset
number
0
ngxScrollToOffsetMap
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**
```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)