Angular Custom Scrollbar
[](https://murhafsousli.github.io/ngx-scrollbar/)
[](https://stackblitz.com/edit/ngx-scrollbar)
[](https://www.npmjs.com/package/ngx-scrollbar)
[](https://www.npmjs.com/package/ngx-scrollbar)
[](https://www.npmjs.com/package/ngx-scrollbar)
[](https://www.npmjs.com/package/ngx-scrollbar)
[](/LICENSE)
Custom overlay-scrollbars with native scrolling mechanism for Angular, it also provides a cross-browser smooth scroll directive.
___
## Table of Contents
- [Live Demo](https://MurhafSousli.github.io/ngx-scrollbar/)
- [Installation](#installation)
- [Usage](#usage)
- [Options](#options)
- [Scroll Functions](#scroll-functions)
- [Styling](#styling)
- [Update scrollbars manually](#manual-update)
- [Smooth Scroll](#smooth-scroll)
- [Virtual Scroll](#virtual-scroll)
- [Development](#development)
- [Issues](#issues)
- [Author](#author)
- [Credit](#credit)
- [More plugins](#more-plugins)
```
Here is a [stackblitz](https://stackblitz.com/edit/ngx-scrollbar)
## Options
### Scrollbar inputs
- **[trackX]**: boolean
Horizontal scrollbar, default `false`
- **[trackY]**: boolean
Vertical scrollbar, default `true`
- **[invertX]**: boolean
Invert horizontal scrollbar position, default `false`
- **[invertY]**: boolean
Invert vertical scrollbar position, default `false`
- **[shown]**: 'native' | 'hover' | 'always', default `native`
Configure when scrollbars should be shown.
- `native`: scrollbars are shown when content is scrollable.
- `hover`: scrollbars are shown when mouse is over the view port (and content is scrollable).
- `always`: scrollbars are always shown.
- **[autoUpdate]**: boolean
Auto-update scrollbars on content changes, default: `true`
- **[viewClass]**: string
Add custom class to the view, default: `null`
- **[barClass]**: string
Add custom class to scrollbars, default: `null`
- **[thumbClass]**: string
Add custom class to scrollbars' thumbnails, default: `null`
- **[compact]**: boolean
Make scrollbars position appears over content, default: `false`
- **[disabled]**: boolean
Disable the custom scrollbars and use the native ones instead, default: `false`
- **[scrollToDuration]**: number
The smooth scroll duration when a scrollbar is clicked, default `400`.
- **[disableOnBreakpoints]**: Array of the CDK Breakpoints
Disable custom scrollbars on specific breakpoints, default: `[Breakpoints.HandsetLandscape, Breakpoints.HandsetPortrait]`
***
> Because it is not possible to hide the native scrollbars on mobile browsers, the only solution is to fallback to the native scrollbars.
> *To disable this option give it false value.*
***
### Scrollbar functions
To use *NgScrollbar* functions, you will need to get the component reference from the template. this can be done using the `@ViewChild` decorator, for example:
```ts
@ViewChild(NgScrollbar) scrollRef: NgScrollbar;
```
**Example:** Subscribe to `NgScrollbar` scroll event
```ts
@ViewChild(NgScrollbar) scrollbarRef: NgScrollbar;
ngAfterViewInit() {
this.scrollbarRef.scrollable.elementScrolled().subscribe(e => console.log(e))
}
```
## Scroll functions
All scroll functions return a cold observable that requires calling `subscribe()`, it will emits once scrolling is done and unsubscribe itself, *no need to unsubscribe from the function manually.*
#### Scroll to position
```ts
scrollRef.scrollTo(options: ScrollToOptions).subscribe()
```
- **Left:** x position.
- **Top:** y position.
- **Duration:** time to reach position in milliseconds, default null.
- **EaseFunc:** the easing function for the smooth scroll.
#### Scroll to element
```ts
scrollRef.scrollToElement(selector, offset?, duration?, easeFunc?).subscribe()
```
- **Selector:** target element selector.
- **Offset:** Set scroll offset, default 0.
- **Duration:** time to reach position in milliseconds, default null.
- **EaseFunc:** the easing function for the smooth scroll.
#### Scroll horizontally
```ts
scrollRef.scrollXTo(position, duration?, easeFunc?).subscribe()
```
#### Scroll vertically
```ts
scrollRef.scrollYTo(position, duration?, easeFunc?).subscribe()
```
- **Position:** scrolling position on Y axis in pixels.
- **Duration:** time to reach position in milliseconds, default null.
- **EaseFunc:** the easing function for the smooth scroll.
#### Scroll to top
```ts
scrollRef.scrollToTop(duration?, easeFunc?).subscribe()
```
#### Scroll to bottom
```ts
scrollRef.scrollToBottom(duration?, easeFunc?).subscribe()
```
#### Scroll to left
```ts
scrollRef.scrollToLeft(duration?, easeFunc?).subscribe()
```
#### Scroll to right
```ts
scrollRef.scrollToRight(duration?, easeFunc?).subscribe()
```
- **Duration:** time to reach position in milliseconds, default null.
- **EaseFunc:** the easing function for the smooth scroll.
## Scrolling examples
### Scroll to top directly from the template
```html
Go to top
```
### Scroll to a specific element
```html
Usage Section
```
Or using the `@ViewChild` decorator
```ts
@ViewChild(NgScrollbar) scrollRef: NgScrollbar;
scrollToUsageSection() {
this.scrollRef.scrollToElement('#usage');
}
```
### Scroll to top on route change
If you wrap the `` with ``, you can scroll to top on route changes, like the following example:
```ts
export class AppComponent {
@ViewChild(NgScrollbar) scrollRef: NgScrollbar;
constructor(router: Router) {
router.events.pipe(
filter(event => event instanceof NavigationEnd)),
filter(() => !!this.scrollRef)),
tap((event: NavigationEnd) => this.scrollRef.scrollToTop())
).subscribe();
}
}
```
#### Update scrollbars manually
**Text area example:**
```ts
Component({
selector: 'text-area-example',
template: `
`
})
export class AppComponent implements OnInit {
@ViewChild(NgScrollbar) textAreaScrollbar: NgScrollbar;
setText(value: string) {
this.text = value;
// You might need to give a tiny delay before updating the scrollbar
setTimeout(() => {
this.textAreaScrollbar.update();
}, 200);
}
}
```
You can also automatically resize the `` with the [CDK Text-field](https://material.angular.io/cdk/text-field/overview).
```html
```
```ts
@ViewChild(NgScrollbar) textAreaScrollbar: NgScrollbar;
@ViewChild(CdkTextareaAutosize) textareaAutosize: CdkTextareaAutosize;
setCode(code: string) {
this.code = code;
this.textareaAutosize.resizeToFitContent();
setTimeout(() => {
this.textAreaScrollbar.update();
}, 200);
}
```
```
```scss
.my-scrollbar {
--scrollbar-color: transparent;
--scrollbar-container-color: transparent;
--scrollbar-thumb-color: rgba(0, 0, 0, 0.2);
--scrollbar-thumb-hover-color: rgba(0, 0, 0, 0.3);
--scrollbar-border-radius: 4px;
--scrollbar-size: 6px;
--scrollbar-padding: 8px;
--scroll-view-margin: 0;
--scroll-view-color: transparent;
}
```
You can also use custom classes to override the styles
```html
```
```scss
::ng-deep {
ng-scrollbar.scrollbar {
background-color: rgba(0, 0, 0, 0.4);
border-radius: 4px;
}
ng-scrollbar.scrollbar-thumbs {
background-color: rgba(161, 27, 27, 0.4);
&:hover,
&:active {
background-color: rgba(161, 27, 27, 0.7);
}
}
}
```
`.
```ts
import { SmoothScrollModule } from 'ngx-scrollbar';
@NgModule({
imports: [
// ...
SmoothScrollModule
]
})
```
```html
Scroll to bottom
```
See all [Scroll Functions](#scroll-functions).
`.
Example:
```html
{{item}}
```
