NgxUiScroll

Unlimited bidirectional scrolling over limited viewport. A directive for Angular framework (version 5). Built with angular-library-starter. Inspired by angular-ui-scroll (AngularJS, since 2013). Demo is available at dhilt.github.io/ngx-ui-scroll.

• Motivation
• Features
• Getting
• Usage
• Developing

Motivation

The common way to present a list of data elements of undefined length is to start with a small portion - just enough to fill the space on the page. Additional blocks are added to the list as the user scrolls to the edge of the list. The problem with this approach is that even though blocks at the edge of the list become invisible as they scroll out of the view, they are still a part of the page and still consume resources.

The *uiScroll directive dynamically destroys elements as they become invisible and recreating them if they become visible again. This is structural directive that works like *ngFor and instantiates a template once per item from a collection. The *uiScroll directive is asking the datasource for data to build and render elements until it has enough elements to fill out the viewport. It will start retrieving new data for new elements again if the user scrolls to the edge of visible element list.

Features

• unlimited virtual scroll
• virtualization settings (you can specify when and how many items need to be requested/rendered by the uiScroll), demos
• infinite mode (items rendered once are never removed), demo
• horizontal mode, demo
• different item heights, demo
• special Adapter API object to manipulate and assess the scroller, demos

Getting

The *uiScroll directive is a part of UiScrollModule which is available via npm –

npm install ngx-ui-scroll

The UiScrollModule has to be imported in the App/feature module where it is going to be used.

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { UiScrollModule } from 'ngx-ui-scroll';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    UiScrollModule
  ],
  bootstrap: [AppComponent]
})
export class AppModule { }

Usage

Basic usage template may look like

<div class="viewport">
  <div *uiScroll="let item of datasource">
    <b>{{item.text}}</b>
  </div>
</div>

where the viewport is a scrollable area of finite height.

.viewport {
    height: 300px;
    overflow-y: auto;
    overflow-anchor: none;
}

*uiScroll acts like *ngFor, but the datasource is an object of special type (IDatasource) that can be imported to the host component from UiScrollModule. It implements method get to be used by the *uiScroll directive to access the data by index and count parameters.

import { IDatasource } from 'ngx-ui-scroll';

export class AppComponent {

  public datasource: IDatasource = {
    get: (index, count, success) => {
      const data = [];
      for (let i = index; i <= index + count - 1; i++) {
        data.push({ text: 'item #' + i });
      }
      success(data);
    }
  };
}

Datasource.get must provide an array of count data-items started from index position. Datasource.get has 3 signatures: callback based, Promise based and Observable based. So, if you want some remote API to be a source of your data, basically it may look like

  public datasource: IDatasource = {
    get: (index, count) =>
      this.http.get(`${myApiUrl}?index=${index}&count=${count}`)
  };

More details could be found on the DEMO page.

Developing

There are some npm scripts available from package.json:

• npm start to run demo App on port 4200
• npm test to run Karma tests
• npm run build to build the ngx-ui-scroll module into the ./dist folder
• npm run install-package to build tar-gzipped version of package and install it locally into ./node_modules

The work has just begun. We have great plans and any participation is welcome! So, feel free to submit new issues and open Pull Requests.

2018 © dhilt, Hill30 Inc