Package Exports
- ngx-scrollbar
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (ngx-scrollbar) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
Angular Custom Scrollbar
Custom overlay-scrollbars with native scrolling mechanism for Angular, it also provides a cross-browser smooth scroll directive.
Table of Contents
- Live Demo
- Installation
- Usage
- Options
- Scroll Functions
- Styling
- Smooth Scroll
- Development
- Issues
- Author
- Credit
- More plugins
Installation
NPM
npm i -S ngx-scrollbar @angular/cdk
YARN
yarn add ngx-scrollbar @angular/cdk
Usage
Import NgScrollbarModule
in your module
import { NgScrollbarModule } from 'ngx-scrollbar';
@NgModule({
imports: [
// ...
NgScrollbarModule
]
})
In your template
<ng-scrollbar>
<!-- Content -->
</ng-scrollbar>
Here is a stackblitz
Options
Scrollbar inputs
[trackX]: boolean
Horizontal scrollbar, default
false
[trackY]: boolean
Vertical scrollbar, default
true
[autoHide]: boolean
Show scrollbar on mouse hover only, default
false
[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
[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.
Update scrollbars manually
By default the input [autoUpdate]
is true, which uses the MutationObserver
to observe child elements changes and update the sizes of the scrollbars, however this does not include text changes so if you want to update the scrollbars on text changes, then you need to do that manually.
Dynamic text example:
Component({
selector: 'text-area-example',
template: `
<ng-scrollbar>
<div class="text-content">
{{text}}
</div>
</ng-scrollbar>
`
})
export class AppComponent implements OnInit {
@ViewChild(NgScrollbar) textScrollbar: NgScrollbar;
setText(value: string) {
this.text = value;
// wait for the new text value to render before updating the scrollbar
setTimeout(() => {
this.textScrollbar.update();
}, 200);
}
}
Text area example:
Component({
selector: 'text-area-example',
template: `
<ng-scrollbar>
<textarea [(ngModel)]="text"></textarea>
</ng-scrollbar>
`
})
export class AppComponent implements OnInit {
@ViewChild(NgScrollbar) textScrollbar: NgScrollbar;
setText(value: string) {
this.text = value;
// wait for the new text value to render before updating the scrollbar
setTimeout(() => {
this.textAreaScrollbar.update();
}, 200);
}
}
You can also automatically resize the <text-area>
with the CDK Text-field.
<ng-scrollbar>
<textarea cdkTextareaAutosize #autosize="cdkTextareaAutosize" [(ngModel)]="code"></textarea>
</ng-scrollbar>
@ViewChild(NgScrollbar) textAreaScrollbar: NgScrollbar;
@ViewChild(CdkTextareaAutosize) textareaAutosize: CdkTextareaAutosize;
setCode(code: string) {
this.code = code;
this.textareaAutosize.resizeToFitContent();
setTimeout(() => {
this.textAreaScrollbar.update();
}, 200);
}
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:
@ViewChild(NgScrollbar) scrollRef: NgScrollbar;
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
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
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
scrollRef.scrollXTo(position, duration?, easeFunc?).subscribe()
- Position: scrolling position on X axis in pixels.
- Duration: time to reach position in milliseconds, default null.
- EaseFunc: the easing function for the smooth scroll.
Scroll vertically
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
scrollRef.scrollToTop(duration?, easeFunc?).subscribe()
- Duration: time to reach position in milliseconds, default null.
- EaseFunc: the easing function for the smooth scroll.
Scroll to bottom
scrollRef.scrollToBottom(duration?, easeFunc?).subscribe()
- Duration: time to reach position in milliseconds, default null.
- EaseFunc: the easing function for the smooth scroll.
Scroll to left
scrollRef.scrollToLeft(duration?, easeFunc?).subscribe()
- Duration: time to reach position in milliseconds, default null.
- EaseFunc: the easing function for the smooth scroll.
Scroll to right
Observable that emits once scrolling to right is done
scrollRef.scrollToRight(duration?, easeFunc?).subscribe(() => {
console.log('scrollToRight is done')
})
- Duration: time to reach position in milliseconds, default null.
- EaseFunc: the easing function for the smooth scroll.
Dynamic scrolling example
Scroll to top directly from the template
<ng-scrollbar #scrollbarRef>
<!-- Content -->
</ng-scrollbar>
<button (click)="scrollbarRef.scrollToTop(500)">Scroll to top</button>
Or using the @ViewChild
decorator
@ViewChild(ScrollbarComponent) scrollRef: ScrollbarComponent;
scrollToTop() {
this.scrollRef.scrollToElement('#usage');
}
Scroll to top on route change
export class AppComponent implements OnInit {
@ViewChild(NgScrollbar) scrollRef: NgScrollbar;
constructor(private router: Router) {
}
ngOnInit() {
this.router.events
.filter(event => event instanceof NavigationEnd)
.subscribe((event: NavigationEnd) => {
if (this.scrollRef) {
this.scrollRef.scrollToTop();
}
});
}
}
Styling
The easiest way to use custom styles is to give each part of the scrollbar a custom class
<ng-scrollbar barClass="scroll-bar" thumbClass="scroll-thumbs">
<!-- child elements... -->
</ng-scrollbar>
.scroll-bar {
background-color: rgba(0, 0, 0, 0.4) !important;
border-radius: 4px;
}
.scroll-thumbs {
background-color: rgba(161, 27, 27, 0.4) !important;
&:hover,
&:active {
background-color: rgba(161, 27, 27, 0.7) !important;
}
}
Smooth Scroll
The [smoothScroll]
directive allows you to scroll the host element smoothly using the scroll functions that works on cross-browser.
Since v3.0.0, The SmoothScrollModule
has been added as an independent module, the scrollable element does not have to be <ng-scrollbar>
.
import { SmoothScrollModule } from 'ngx-scrollbar';
@NgModule({
imports: [
// ...
SmoothScrollModule
]
})
<div smoothScroll #scrollable class="scrollable-container}">
<!-- child elements -->
</div>
<button (click)="scrollable.scrollToBottom(500)">Scroll to bottom</button>
See all Scroll Functions.
Development
This project uses the Angular CLI for building the library.
$ ng build ngx-scrollbar --prod
or
$ npm run build-lib
Issues
If you identify any errors in the library, or have an idea for an improvement, please open an issue.
Author
Credit
- Inspired by gemini-scrollbar.