CbjScrollbar

This package allows you to easily create custom scrollbars with Angular 5. Currently tested on Chrome and Firefox and running very well. Demo/Docs

Table of Contents

• Install
• Import
• Usage
  • Main Scrollbar
  • Cards
• Config
• Defaults
• Services

Install

npm i --save @codebyjordan/scrollbar

Import

// app.module.ts
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
import { CbjScrollbarModule } from '@codebyjordan/scrollbar';
 
@NgModule({
  imports: [
    BrowserModule,
    CbjScrollbarModule.forRoot()
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Usage

Some examples to get started.

As the windows main scrollbar

Here I am going to override the browsers scrollbar and use this as the main windows scrollbar. I will be using a minimal setup for demonstration purposes, see the Configuration section for more options.

app.component.ts

import {Component, OnInit} from '@angular/core';
import {ScrollbarOptions, ScrollbarConfig} from '@codebyjordan/scrollbar';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styles: ['./app.component.scss']
})
export class AppComponent implements OnInit {
  mainScrollbar: ScrollbarConfig;

  ngOnInit() {
    this.mainScrollbar = new ScrollbarConfig({
      isRoot: true,
      alwaysVisible: true
    });
  }
}

app.component.html

<div class="container-fluid wrapper">
     <div class="row">
         <nav class="navbar cbj-elevation-3 navbar-expand navbar-dark bg-primary w-100">
             <div class="collapse navbar-collapse">
                 <ul class="navbar-nav mr-auto">
                     <li class="nav-item">
                         <a routerLink="/home" routerLinkActive="active" class="nav-link">Home</a>
                     </li>
                     <li class="nav-item">
                         <a class="nav-link" routerLink="/getting-started" routerLinkActive="active">Getting Started</a>
                     </li>
                     <li class="nav-item">
                         <a class="nav-link" routerLink="/usage" routerLinkActive="active">Usage</a>
                     </li>
                 </ul>
             </div>
         </nav>
     </div>
 
     <div class="row">
         <div class="main-content" [cbjScrollbar]="mainScrollbar">
             <router-outlet></router-outlet>
         </div>
     </div>
 </div>

app.component.scss

$navbar-height: 3.25rem;

.main-content {
  height: calc(100vh - #{$navbar-height});
  width: 100%;
}

Cards (multiple)

In this example I make three BS4 cards with a height of 350px and some Lipsum text. Each one has a slightly different configuration and look.

card-demo.component.ts

import {Component, OnInit} from '@angular/core';
import {ScrollbarOptions, ScrollbarConfig} from '@codebyjordan/scrollbar';

@Component({
  selector: 'app-card-demo',
  templateUrl: './card-demo.component.html',
  styleUrls: ['./card-demo.component.scss']
})
export class CardDemoComponent implements OnInit {
  firstCardScroll: ScrollbarConfig;
  secondCardScroll: ScrollbarConfig;
  thirdCardScroll: ScrollbarConfig;

  ngOnInit(): void {
      this.firstCardScroll = new ScrollbarConfig({
        styles: {
          grid: {
            'border-top-right-radius': '.25rem',
            'border-bottom-right-radius': '.25rem',
            'opacity': '.75',
            'background': '#1F2421',
          },
          bar: {
            'background': '#216869'
          },
        },
        alwaysVisible: true
      });
  
      this.secondCardScroll = new ScrollbarConfig({styles: {bar: {'background': '#2274A5'}}});
  
      this.thirdCardScroll = new ScrollbarConfig({
        styles: {
          bar: {
            'opacity': '.65',
            'background': '#1F2421'
          }
        },
        alwaysVisible: true
      });
    }
}

card-demo.component.html

<div class="container py-4">
    <div class="row">
        <div class="col">
            <div class="card scroll-card">
                <div class="card-body" [cbjScrollbar]="firstCardScroll">
                    ...
            </div>
        </div>
    </div>

    <div class="row">
        <div class="col">
            <div class="card mt-4 scroll-card bg-secondary text-white">
                <div class="card-body" [cbjScrollbar]="secondCardScroll">
                    ...
            </div>
        </div>
    </div>

    <div class="row">
        <div class="col">
            <div class="card mt-4 scroll-card bg-primary text-white">
                <div class="card-body" [cbjScrollbar]="thirdCardScroll">
                    ...
                </div>
            </div>
        </div>
    </div>
</div>

card-demo.component.scss

.scroll-card {
  height: 350px;
  padding: 0 1.5rem;
  border: none;
  overflow: hidden;
}

Configuration

You must pass an instance of ScrollbarConfig to the directive for it to function. However, how much you configure is up to you. It is possible to go with no configuration at all and only pass {} to the ScrollbarConfig constructor.

ScrollbarConfig

The ScrollbarConfig constructor takes a single argument using the ScrollbarOptions interface. Use this interface to configure the scrollbar. The available options are:

export interface ScrollbarOptions {
  isRoot?: boolean;
  position?: string;
  alwaysVisible?: boolean;
  visibleTimeout?: number;
  gridOffset?: string | number;
  barOffset?: string | number;
  toggleClasses?: Subject<{ el: string, classes: string, remove: boolean }>;
  styles?: ScrollbarStyles;
  classes?: ScrollbarClasses;
}

export interface ScrollbarStyles {
  wrapper?: { [prop: string]: string | number };
  grid?: { [prop: string]: string | number };
  bar?: { [prop: string]: string | number };
}

export interface ScrollbarClasses {
  wrapper?: string;
  grid?: string;
  bar?: string;
}

isRoot

• Type: boolean
• Default: false

Flag to set when the scrollbar is used as the main windows scrollbar Setting isRoot to true does the following things:

• Prevents the main window from scrolling if an inner window is scrolling.
• Creates an observable that broadcasts the current scroll position on scroll.
• Sets the scroll position and height on the ScrollbarService
• If the RouterModule is present it will listen for Route changes and scroll to top on route change

position

• Type: string
• Default: 'right'

The position of the scrollbar. Valid options are 'right' and 'left'.

alwaysVisible

• Type: boolean
• Default: false

Boolean setting whether the scrollbar hides after a timeout.

visibleTimeout

• Type: number
• Default: 3000

The timeout in milliseconds for hiding the scrollbar.

barOffset

• Type: number | string
• Default: '.5rem''

The bars offset. Must be a valid css value for the left or right property.

gridOffset

• Type: number | string
• Default: 0

The grids offset. Must be a valid css value for the left or right property.

toggleClasses

• Type: Subject<{ el: string, classes: string, remove: boolean }>
• Default: undefined

A Subject that can be used to toggle classes on the wrapper, grid, or bar elements.

styles

• Type: ScrollbarStyles
• Default: See Below

The ScrollbarStyles interface has a key for each the wrapper, grid, and bar element, each of which takes an object with valid css properties as keys with either string or number values.

classes

• Type: ScrollbarClasses
• Default: See Below

The ScrollbarClasses interface has a key for each the wrapper, grid, and bar element that accept a string of class(es) to be applied to the element.

Defaults

export const DEFAULT_SCROLLBAR: ScrollbarOptions = {
  isRoot: false,
  position: 'right',
  alwaysVisible: false,
  visibleTimeout: 3000,
  gridOffset: 0,
  barOffset: '.5rem',
  styles: {
    wrapper: {
      'width': '100%',
      'overflow': 'hidden',
      'display': 'flex'
    },
    grid: {
      'position': 'absolute',
      'top': 0,
      'bottom': 0,
      'display': 'block',
      'cursor': 'pointer',
      'z-index': 99999,
      'background': 'transparent',
      'width': '1rem',
      'border-radius': 0,
      'margin': 0,
      'transition': 'opacity 250ms ease-in-out'
    },
    bar: {
      'position': 'absolute',
      'top': 0,
      'display': 'block',
      'cursor': 'pointer',
      'transition': 'opacity 250ms ease-in-out',
      'z-index': 100000,
      'background': '#495057',
      'width': '.7rem',
      'border-radius': '10px',
      'margin': 0
    }
  },
  classes: {
    wrapper: 'cbj-scroll-wrapper',
    grid: 'cbj-scroll-grid',
    bar: 'cbj-scroll-bar'
  }
};

Services

The package provides 2 services and an Injectable token.

ScrollbarService

The scrollbar service provides a convenient way of interacting with the scrollbar and, mainly, getting information about like scroll position, scroll height, and an elements distance from the top or bottom. Internally, the service is used by the directive to create Observables for responding to the mouse wheel and drag events.

Properties

The ScrollbarService properties

scrollObs

• Type: Observable<number>

Observable of the scroll event. Broadcasts current scroll position on update.

scrollPos

• Type: number

The current scroll position.

scrollHeight

• Type: number

The scrollHeight of the root scrollbars element or document.documentElement.scrollHeight if no root scrollbar.

childScrolling

• Type: boolean

Boolean indicating whether a non root scrollbar is currently scrolling.

Methods

ScrollbarService Methods

getOffsetTop(el): number

Returns the passed elements offset top value

getOffsetBottom(el): number

Returns the passed elements offset bottom value

WindowService

Properties

The WindowService properties

window

• Type: Window

The browsers Window object

resizeObs

• Type: Observable<any>

Observable of the window resize event.

isMobile

• Type: number

Boolean indicating if on mobile sized display.

width

• Type: number

The width of the browsers window.

height

• Type: number

The height of the viewport. If a scrollbar has been created with isRoot set to true, this will be the height of the host element, otherwiseit is the window.innerHeight property