nicholasalx / ngx-scrollbar

Custom overlay-scrollbars with native scrolling mechanism

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
• Update scrollbars manually
• 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

• [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:

@ViewChild(NgScrollbar) scrollRef: NgScrollbar;

Example: Subscribe to NgScrollbar scroll event

@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

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()

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()

Scroll to bottom

scrollRef.scrollToBottom(duration?, easeFunc?).subscribe()

Scroll to left

scrollRef.scrollToLeft(duration?, easeFunc?).subscribe()

Scroll to right

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

<ng-scrollbar #scrollbarRef>
  <!-- Content -->
</ng-scrollbar>

<button (click)="scrollbarRef.scrollToTop()">Go to top</button>

Scroll to a specific element

<ng-scrollbar #scrollbarRef>
  <div id="..."></div>
  <div id="..."></div>
  <div id="..."></div>
  <div id="usage"></div>
  <div id="..."></div>
</ng-scrollbar>

<button (click)="scrollbarRef.scrollToElement('#usage')">Usage Section</button>

Or using the @ViewChild decorator

@ViewChild(NgScrollbar) scrollRef: NgScrollbar;

scrollToUsageSection() {
  this.scrollRef.scrollToElement('#usage');
}

Scroll to top on route change

If you wrap the <router-outlet> with <ng-scrollbar>, you can scroll to top on route changes, like the following example:

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:

Component({
  selector: 'text-area-example',
  template: `
    <ng-scrollbar>
      <textarea [(ngModel)]="text"></textarea>
    </ng-scrollbar>
  `
})
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 <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);
}

Styling

Since v3.4.0, you can customize the scrollbar styles from the following CSS variables

<ng-scrollbar class="my-scrollbar">
  <!-- content -->
</ng-scrollbar>

.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

<ng-scrollbar barClass="scrollbar" thumbClass="scrollbar-thumbs">
  <!-- content -->
</ng-scrollbar>

::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);
    }
  }
}

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

• Murhaf Sousli Github, Twitter

Credit

• Inspired by gemini-scrollbar.

More plugins

• ngx-sharebuttons
• ngx-gallery
• ngx-progressbar
• ngx-scrollbar
• ngx-bar-rating
• ngx-disqus
• ngx-wordpress
• ngx-highlightjs
• ngx-teximate