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.

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

$ npm run build-lib

Issues

If you identify any errors in the library, or have an idea for an improvement, please open an issue.

ngx-scrollbar