Usage

Installation

To install ngx-scrollbar, along with its dependency @angular/cdk, you can use npm:

npm i ngx-scrollbar@beta @angular/cdk

Usage

After installation, import NgScrollbarModule into your component imports:

import { NgScrollbarModule } from 'ngx-scrollbar';

@Component({
  standalone: true,
  selector: 'app-root',
  templateUrl: './app.html',
  imports: [
    NgScrollbarModule
  ]
})

Then, in your component template, you can use the <ng-scrollbar> to wrap your content:

<ng-scrollbar>
  <!-- content goes here -->
</ng-scrollbar>

NgScrollbar API

<ng-scrollbar> has the following are the inputs / outputs:

Name	Default value	Description
[track]	`vertical`	Directions to track `horizontal`, `vertical`, `all`.
[position]	`native`	Invert scrollbar position `native`,`invertX`,`invertY`, `invertAll`.
[visibility]	`native`	Scrollbar visibility `native`, `hover`, `always`.
[appearance]	`standard`	Scrollbar appearance `standard`, `compact`.
[trackClass]	null	Add a class to scrollbars' tracks.
[thumbClass]	null	Add a class to scrollbars' thumbnails.
[trackClickDuration]	50	The smooth scroll step duration when a scrollbar is clicked.
[minThumbSize]	20	The minimum scrollbar thumb size in px.
[sensorThrottleTime]	0	The throttle time used for detecting changes size changes.
[disableSensor]	false	Whether `ResizeObserver` is disabled.
[disableInteraction]	false	Disables scrollbar interaction like dragging thumb and jumping by track click.
(afterInit)	-	Output that emits after the scrollbar component is initialized.
(afterUpdate)	-	Output that emits after the scrollbar component is updated.
scrollTo(options)		Scroll function that returns a promise that resolves when scroll is reached.
scrollToElement(target, options?)	-	Scroll function that returns a promise that resolves when scroll is reached.

Advanced usage: select a custom viewport element

The externalViewport directve allows you to designate another element as the viewport, you can select an external viewport using the scrollViewport directive. if the element is inaccessible from the template, you can pass its selector as the directive value [externalViewport]=".my-custom-viewport".

Example of an external viewport using `scrollViewport` directive:

<ng-scrollbar externalViewport>
  <div scrollViewport>
     <!-- content goes here -->
  </div>
</ng-scrollbar>

Example of an external viewport by passing a selector to `externalViewport` directive:

<ng-scrollbar externalViewport=".my-custom-viewport">
  <div class="my-custom-viewport">
     <!-- content goes here -->
  </div>
</ng-scrollbar>

By default a content wrapper element will be created inside the viewport to hold its content. optionally, you can select a custom content wrapper using the input [externalContentWrapper]

<ng-scrollbar externalViewport=".my-custom-viewport"
              externalContentWrapper=".my-custom-content-wrapper">
  <div class="my-custom-viewport">
    <div class="my-custom-content-wrapper">
       <!-- content goes here -->
    </div>
  </div>
</ng-scrollbar>

This capability enables integration of the scrollbar with 3rd-party libraries where the viewport or content wrapper elements are inaccessible from the template.

NgScrollbarExt API

<ng-scrollbar externalViewport> extends <ng-scrollbar> with the following inputs:

Name	Default value	Description
[externalViewport]	null	External viewport selector.
[externalContentWrapper]	null	External content wrapper selector.
[externalSpacer]	null	External spacer selector used for calculating content dimensions instead of using the content wrapper (useful for virtual scroll libraries).