Need help with od-virtualscroll?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

dinony
133 Stars 13 Forks MIT License 93 Commits 10 Opened issues

Description

🚀 Observable-based virtual scroll implementation in Angular

Services available

!
?

Need anything else?

Contributors list

No Data

od-virtualscroll

GitHub license Module format Module format gzip size

Observable-based virtual scroll implementation in Angular.

Installation

npm i -S od-virtualscroll

Features

Let's you scroll efficiently through a humongous list/grid of items (with single predefined height) by recycling components and minimizing component updates.

  • Handles resizing
  • Efficient
    • Displays necessary amount of rows
    • Optimal updates on data change or resize
  • Supports tiling
  • Supports fixed number of columns
  • Reactive component
    • Observable interface for most parts
  • Supports AoT
  • API
    • Subscribe to key component observables
  • Plus
    • Debounce scrolling / resizing
    • Set scroll position, focus row or item via index
    • Customizable equality checking
    • A lot of code samples
  • Module formats
    • Ships FESM5 and FESM15
    • Ships ES5/UMD, ES5/ES2015 and ES2015/ES2015 exports (
      {{target}}/{{module}}
      )

Demo

All examples are written in Angular 4 and provided in separate repositories to keep this repository simple.

| Name | Description |----------------|------------------------------------- | od-vsstatic / Demo | Static example with 100k cells. Ideal for performance analysis and GC testing | od-vsdynamic / Demo | Scroll through GIFs, without the risk of a CPU meltdown (GIPHY API) | od-vslist / Demo | Render only 1 cell per row with dynamic width (randomuser API) | od-vsadvanced / Demo | Shows more advanced API features and utilizes the auxiliary debug module | od-vscolors / Demo | Just for fun

However, this repository also holds a minimalistic demo, to allow local development and AoT compilation.

Usage

Import the module and specify the cell and container styling (traditional layout or flexbox/... your choice).

// app.module.ts
import {NgModule} from '@angular/core';
import {BrowserModule} from '@angular/platform-browser';
import {VirtualScrollModule} from 'od-virtualscroll';
import {AppComponent} from './app.component';

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

// app.component.ts import {Component} from '@angular/core'; import {Observable} from 'rxjs'; import {IVirtualScrollOptions} from 'od-virtualscroll';

@Component({ selector: 'app-shell', styles: [...], // Row: {{row}}
Column: {{column}} {{item}} ` }) export class AppComponent { data$: Observable = ... ; // = ... ; //

If you want to apply a traditional layout and wonder about the space between inline block elements - read this.

Inputs

| Name | Type | Description |------------------|---------------------------------------------------|------------------------------------------------------------------------------------------------------- | vsData |

Observable
| Stream of data | vsOptions |
Observable
| Stream of options | vsResize |
Observable
| Stream of resize commands (optional, default:
-\->
) | vsUserCmd |
Observable
| Stream of user specific commands (optional, default:
-\->
) | vsDebounceTime |
number
| Debounce scroll and resize events ms | vsEqualsFunc |
(prevIndex: number, curIndex:number) => boolean
| Function to determine equality, given two indicies in the array (optional, default:
(p,c) => p === c)
)

IVirtualScrollOptions

export interface IVirtualScrollOptions {
  itemWidth?: number;
  itemHeight: number;
  numAdditionalRows?: number;
  numLimitColumns?: number;
}

The component requires either fixed-size cells (itemWidth, itemHeight) or a fixed number of cells per row (itemHeight, numLimitColumns).

Further, to improve scrolling, additional rows may be requested.

IUserCmd

Currently, the supported user specific commands are:

  • SetScrollTopCmd
    : Set scroll top to specific value
  • FocusRowCmd
    : Focus specific row index
  • FocusItemCmd
    : Focus specific item index

E.g. Focus row index 42.

data$ = // Data...;
userCmd$ = of(new FocusRowCmd(42)).pipe(delay(2000));
  

API

ScrollObservableService

Inject the ScrollObservableService to subscribe to key component observables.

| Name | Type | Description |------------------|------------------------------------------------------------|------------------------------------------------------- | scrollWin$ |

[IVirtualScrollWindow]
| Stream of the most important inner data structure | createRow$ |
[CreateRowCmd,  ComponentRef]
| Create row command and ComponentRef | removeRow$ |
[RemoveRowCmd, ComponentRef]
| Remove row command and ComponentRef | shiftRow$ |
[ShiftRowCmd, ComponentRef]
| Shift row command and ComponentRef | createItem$ |
[CreateItemCmd, ScrollItem, EmbeddedViewRef]
| Create item command, scroll item and EmbeddedViewRef | updateItem$ |
[UpdateItemCmd, ScrollItem, EmbeddedViewRef]
| Update item command, scroll item and EmbeddedViewRef | removeItem$ |
[RemoveItemCmd]
| Remove item command

The od-vsdynamic and od-vsadvanced examples show how the API may be used.

IVirtualScrollWindow

This interface provides pretty much all needed information.

export interface IVirtualScrollWindow {
  dataTimestamp: number;
  containerWidth: number;
  containerHeight: number;
  itemWidth?: number;
  itemHeight: number;
  numVirtualItems: number;
  numVirtualRows: number;
  virtualHeight: number;
  numAdditionalRows: number;
  scrollTop: number;
  scrollPercentage: number;
  numActualRows: number;
  numActualColumns: number;
  actualHeight: number;
  numActualItems: number;
  visibleStartRow: number;
  visibleEndRow: number;
}

It is used internally and may also be useful in consuming application components.

E.g.: The od-vsdynamic example.

Multiple Instances

The

ScrollObservableService
is registered on the VirtualScrollModule by default, so it is available on the root injector. However, if you have multiple instances of the scroll component, a singleton instance of the
ScrollObservableService
is not enough. Register the service on the wrapping component, via the providers property in the
@Component
decorator, so that the injector bubbling will stop on the Component level and will serve the right instance of the ScrollObservableService.

Check the feature/testMultiInstances branch for a simple example.

Further information

api.ts reveals the current API surface.

Module Format

The lib is AoT compatible and ships with FESM5 and FESM15 exports.

See Angular Package Format v4.0 for more info.

ES5/UMD, ES5/ES2015 and ES2015/ES2015 exports are also provided.

Upgrade

1.0.x -> 1.1.x

1.1.x uses Angular6/RxJS6.

0.2.x -> 1.x

Rename component input

vsScrollTop
to
vsUserCmd
.

NPM Scripts

npm run {{scriptName}}

| Name | Description |---------------|------------------------------------------- | buildAll | Build lib and demo | cleanAll | Remove generated directories | buildDemo | Build demo bundle with AoT compilation | tslint | Lint lib and demo | serve | Starts browser-sync for local development | explore | Source map explorer of AoT compiled demo

Contribution & Contact

Contribution and feedback is highly appreciated.

GitHub

Twitter

License

MIT

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.