-
-
Notifications
You must be signed in to change notification settings - Fork 99
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
ef964b1
commit 72ac305
Showing
40 changed files
with
2,313 additions
and
34 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| To set global options for all scrollbar components across the app, provide the token `NG_SCROLLBAR_OPTIONS` with your custom options like in the following example: | ||
|
|
||
| ```ts | ||
| import { NgScrollbarModule, NG_SCROLLBAR_OPTIONS } from 'ngx-scrollbar'; | ||
|
|
||
| @NgModule({ | ||
| imports: [ | ||
| NgScrollbarModule | ||
| ], | ||
| providers: [ | ||
| { | ||
| provide: NG_SCROLLBAR_OPTIONS, | ||
| useValue: { | ||
| // ... options | ||
| } | ||
| } | ||
| ] | ||
| }) | ||
| ``` | ||
|
|
||
| #### Global options API (`NgScrollbarOptions`) | ||
|
|
||
|
|
||
| | 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** | `compact` | Scrollbar appearance `standard`, `compact`. | | ||
| | **viewClass** | *null* | Add custom class to the viewport element. | | ||
| | **trackClass** | *null* | Add custom class to scrollbar track elements. | | ||
| | **thumbClass** | *null* | Add custom class to scrollbar thumbnail elements. | | ||
| | **trackClickScrollDuration**| 300 | The smooth scroll duration when a scrollbar is clicked. | | ||
| | **minThumbSize** | 20 | The minimum scrollbar thumb size in px. | | ||
| | **scrollAuditTime** | 0 | Throttle scroll event in ms. | | ||
| | **windowResizeDebounce** | 0 | Debounce interval for detecting changes via `window.resize` event. | | ||
| | **sensorDebounce** | 0 | Debounce interval for detecting changes via `ResizeObserver`. | | ||
| | **sensorDisabled** | false | Whether `ResizeObserver` is disabled. | | ||
| | **pointerEventsMethod** | `viewport` | The method used to detect scrollbar pointer-events, [read more](pointer-events). | | ||
| | **pointerEventsDisabled** | false | Enable/disable the scrollbar track clicked and thumb dragged events. | | ||
| | **autoHeightDisabled** | false | Whether to set component height to content height. | | ||
| | **autoWidthDisabled** | true | Whether to set component width to content width. | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,95 @@ | ||
| The `scrollViewport` directive allows you to use a custom viewport element in your template. It is used for integration with other libraries where the viewport can be another component or directive. | ||
|
|
||
| ### Basic usage | ||
|
|
||
| ```html | ||
| <ng-scrollbar> | ||
| <div scrollViewport class="custom-viewport"> | ||
| <div class="scroll-content-wrapper"> | ||
| <!-- content --> | ||
| </div> | ||
| </div> | ||
| </ng-scrollbar> | ||
| ``` | ||
|
|
||
| > **NOTE**: `scrollViewport` directive must be used on the direct child of `<ng-scrollbar>` | ||
| > **NOTE**: When `scrollViewport` directive is used on an element, It is recommended that its host element to have one and only one child element that acts as a content wrapper _(like `.scroll-content-wrapper` in the above example)_, this content wrapper will be used by the ResizeObserver API to observes content changes and updates the UI accordingly. | ||
| > **IMPORTANT NOTE:** Some external libraries can cause the scrollbar to recalculate very frequently when it scrolls, which can result in flickering behaviour (like the CDK virtual scroll viewport). | ||
| To avoid this, set `[autoHeightDisabled]="true"` | ||
|
|
||
| ### Integrate with [ngx-infinite-scroll](https://github.com/orizens/ngx-infinite-scroll). | ||
|
|
||
| ```html | ||
| <ng-scrollbar> | ||
| <div infiniteScroll [scrollWindow]="false" scrollViewport> | ||
| <mat-list> | ||
| <mat-list-item class="example-item" *ngFor="let i of array"> | ||
| {{ i }} | ||
| </mat-list-item> | ||
| </mat-list> | ||
| </div> | ||
| </ng-scrollbar> | ||
| ``` | ||
|
|
||
| ### Integrate with [CDK Scrollable](https://material.angular.io/cdk/scrolling/overview#cdkscrollable-and-scrolldispatcher) | ||
|
|
||
| If you need to get hold of the scrollable element of the component, you can add a child element and then assign it with `scrollViewport` directive | ||
|
|
||
| ```html | ||
| <ng-scrollbar> | ||
| <div scrollViewport cdkScrollable> | ||
| <!-- CONTENT --> | ||
| </div> | ||
| </ng-scrollbar> | ||
| ``` | ||
|
|
||
| ### Integrate with [CDK VirtualScroll](https://material.angular.io/cdk/scrolling/overview#virtual-scrolling). | ||
|
|
||
|
|
||
| ```html | ||
| <ng-scrollbar> | ||
| <cdk-virtual-scroll-viewport itemSize="50" scrollViewport> | ||
| <div *cdkVirtualFor="let item of items">{{item}}</div> | ||
| </cdk-virtual-scroll-viewport> | ||
| </ng-scrollbar> | ||
| ``` | ||
|
|
||
| ### Integrate with [CDK Drag and Drop](https://material.angular.io/cdk/drag-drop/overview) | ||
|
|
||
| ```html | ||
| <ng-scrollbar track="horizontal" appearance="standard"> | ||
|
|
||
| <div class="tabs" | ||
| scrollViewport | ||
| #tabDropList="cdkDropList" | ||
| dropListScroller | ||
| cdkDropList | ||
| cdkDropListLockAxis="x" | ||
| cdkDropListOrientation="horizontal" | ||
| [cdkDropListAutoScrollDisabled]="true" | ||
| (cdkDropListDropped)="drop($event)"> | ||
|
|
||
| <div class="tab" *ngFor="let tab of tabs" | ||
| [ngClass]="{ selected: selectedTab === tab.id }" | ||
| cdkDrag | ||
| [cdkDragData]="tab" | ||
| (cdkDragStarted)="onDragStarted($event)" | ||
| (mousedown)="selectedTab = tab.id" | ||
| (click)="onSelectTab(tab)"> | ||
| <span class="tab-label">{{ tab.label }}</span> | ||
| <span class="tab-close pi pi-times"></span> | ||
| </div> | ||
|
|
||
| </div> | ||
| </ng-scrollbar> | ||
| ``` | ||
| ```scss | ||
| ng-scrollbar { | ||
| height: 70px; | ||
| width: 100%; | ||
| } | ||
| ``` | ||
|
|
||
| Demo: https://stackblitz.com/edit/ngx-scrollbar-cdk-drag-drop |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| # Regarding the scroll event | ||
|
|
||
| By default, the scroll event is used to do the necessary calculation to display the custom scrollbars. | ||
|
|
||
| You may want to tweak the scroll event if it is not performing well on low-end devices. | ||
|
|
||
| You can throttle the scroll event using the `scrollAuditTime` option, `20` milliseconds seems to be a reasonable value. | ||
|
|
||
| **Example:** | ||
|
|
||
| Set the option `[scrollAuditTime]` for a specific scrollbar component. | ||
|
|
||
| ```html | ||
| <ng-scrollbar [scrollAuditTime]="20"> | ||
| <!-- ...content... --> | ||
| </ng-scrollbar> | ||
| ``` | ||
|
|
||
| **Example:** | ||
|
|
||
| Set the `scrollAuditTime` option for all custom scrollbars using the global options. | ||
|
|
||
| ```ts | ||
| import { NgScrollbarModule, NG_SCROLLBAR_OPTIONS } from 'ngx-scrollbar'; | ||
|
|
||
| @NgModule({ | ||
| imports: [ | ||
| NgScrollbarModule | ||
| ], | ||
| providers: [ | ||
| { | ||
| provide: NG_SCROLLBAR_OPTIONS, | ||
| useValue: { | ||
| scrollAuditTime: 20 | ||
| } | ||
| } | ||
| ] | ||
| }) | ||
| ``` | ||
|
|
||
| _This option is available in `ngx-scrollbar >= v7.1.0`_ | ||
|
|
||
| # Regarding the `auto-height` and `auto-width` features | ||
|
|
||
| When any of these features is turned on, the scrollbar will re-calculate when the component size or the content size change. | ||
|
|
||
| If the scrollbar is used with other library that frequently changes the content or the component size, it could cause a performance issue, therefore, you should turn them off. | ||
|
|
||
| For example when using it with a virtual scroll library, you should set `[autoHeightDisabled]="true"` (which is already disabled by default). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| The pointer-events here means the method this library use to detect the dragging of the scrollbar and the hover effect on the scrollbar | ||
|
|
||
| There are 2 methods to detect pointer events | ||
|
|
||
| ```html | ||
| <ng-scrollbar pointerEventsMethod="viewport"> | ||
| ``` | ||
|
|
||
| - `pointerEventsMethod="viewport"`, will detect pointer events using viewport's `mousemove`, `mousedown` and `mouseleave` events. | ||
|
|
||
| - `pointerEventsMethod="scrollbar"`, will detect pointer events using scrollbar `mousedown`, `mouseenter` and `mouseleave` event. | ||
|
|
||
| ### In a nutshell, here are the pros and cons of each method with the `[appearance]` option: | ||
|
|
||
| <table> | ||
| <thead> | ||
| <tr> | ||
| <th>Appearance ↓</th> | ||
| <th>viewport</th> | ||
| <th>scrollbar</th> | ||
| </tr> | ||
| </thead> | ||
| <tbody> | ||
| <tr> | ||
| <td><b>Standard</b></td> | ||
| <td> | ||
| <ul> | ||
| <li><u>Only if both scrollbars appear</u>, the content may overlap under the scrollbar</li> | ||
| <li>Scrolling over scrollbar works</li> | ||
| </ul> | ||
| </td> | ||
| <td> | ||
| <ul> | ||
| <li>The content never overlap under the scrollbars</li> | ||
| <li>Scrolling over scrollbar doesn't work</li> | ||
| </ul> | ||
| </td> | ||
| </tr> | ||
| <tr> | ||
| <td><b>Compact</b></td> | ||
| <td> | ||
| <ul> | ||
| <li>Content overlaps under the scrollbar as intended</li> | ||
| <li>Scrolling over scrollbar works</li> | ||
| </ul> | ||
| </td> | ||
| <td> | ||
| <ul> | ||
| <li>The content overlaps under the scrollbar as intended</li> | ||
| <li>Scrolling over scrollbar doesn't work</li> | ||
| </ul> | ||
| </td> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
|
|
||
| --- | ||
|
|
||
| > **My recommendation:** If scrolling over scrollbar isn't a big deal, then go with `pointerEventsMethod="scrollbar"`. | ||
| --- | ||
|
|
||
| *Theoretically `scrollbar` method is more performant because `viewport` method checks if the pointer is over the scrollbars while the pointer is moving over the viewport.* | ||
|
|
||
| *But most of the time, there won't be any difference in performance unless you have a complex design. try both and see what best fits your app.* | ||
|
|
||
| ### 📌 Note | ||
|
|
||
| The pointer-events are disabled on mobile browsers by design. because there is no pointer 😄 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| ## Documentation for v13 | ||
|
|
||
| - [Demo for v13](https://ngx-scrollbar-v13.netlify.app/) | ||
| - [Usage](Usage-v13.md) | ||
| - [Styling](Styling-v13.md) | ||
| - [Global Options](Global-Options-v13.md) | ||
| - [Pointer Events](Pointer-Events-v13.md) | ||
| - [Scroll Event](scroll-event.md) | ||
| - [Updated Event](Updated-event-v13.md) | ||
| - [Smooth Scroll Functions](Smooth-scroll-functions-v13.md) | ||
| - [Performance tweak](Performance-tweak-v13.md) | ||
| - [Integration](Integration-v13.md) | ||
| - [Infinite Scroll](Integration-v13.md#integrate-with-ngx-infinite-scroll) | ||
| - [CDK Scrollable](Integration-v13.md#integrate-with-cdk-scrollable) | ||
| - [CDK Virtual Scroll](Integration-v13.md#integrate-with-cdk-virtualscroll) | ||
| - [CDK Drag and Drop](Integration-v13.md#integrate-with-cdk-drag-and-drop) | ||
| - [Reached events](reached-events-v13.md) | ||
|
|
||
| --- | ||
|
|
||
| - [Smooth Scroll Module (without NgScrollbar)](Smooth-Scroll-v13.md) | ||
|
|
Oops, something went wrong.
72ac305There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎉 Published on https://ngx-scrollbar.netlify.app as production
🚀 Deployed on https://66f4efe19f4c78651dec62e6--ngx-scrollbar.netlify.app