scrolling-assistant v1.0.0

Scrolling Assistant

Angular 8+ Directives that help getting more information out of page scrolls.
You will be able to understand in which direction an Element is scrolling, where the scrollbar is resting and how much was scrolled.

Why ?

Mostly because I had to deal with scrolling and wanted to know how it works in a browser.

At work I was working on some applications and I had to implement a view that worked like a chat: loading older messages when scrolling up, then I had to implement a progress bar that would track how much a page was scrolled.

Looking around I found many libraries for Javascript and Angular that I could use, but almost all of them offered way too much functionality or were outdated so I decided to try write something myself.

This library is kept very simple with a very small surface, so don't expect the ultimate scrolling library.
If you want something simple for simple use cases you are in the right place.

How do I use it ?

You can checkout the example project scrolling-assistant-playground by running npm start.

You will get two directives: HorizontalScrollAssistantDirective and VerticalScrollAssistantDirective. Each directive takes care of a particular scrolling direction (I'm sure I don't have to tell you which one tracks what).

To get access to the directives first import the ScrollingAssistantModule and add it to your Angular Module imports array, like so:

import { ScrollingAssistantModule } from 'scrolling-assistant';

@NgModule({
  declarations: [
    ...
  ],
  imports: [
    ...,
    ScrollingAssistantModule,
    ...
  ],
  providers: [],
  bootstrap: [
    ...
  ]
})
export class SomeAngularModule { }

You can apply each directive on any element that scrolls like so:

<div (verticalScrollAssistant)="onVerticalScroll($event);" 
    (horizontalScrollAssistant)="onHorizontalScroll($event);">
    ...
</div>

Doing so will let you have access to the HorizontalScrollStatus and VerticalScrollStatus data in the event handler.

Each directive also exposes other events to make it easy to react to certain scroll movements.

For horizontal scroll you can subscribe to:

atLeft: triggered everytime the horizontal scroll bar is completely on the left (the element was not scrolled).
atRight same as atLeft but triggered only when the scroll bar is completely to the right (the element is completely scrolled).
scrollingLeft: emitted when a scroll event was fired and the element was scrolled to the left.
scrollingRight: emitted when a scroll event was fired and the element was scrolled to the right.

For vertical scroll you can subscribe to:

onTop: triggered everytime the vertical scroll bar is completely on top (the element was not scrolled)
atBottom: like onTop but when the scroll bar has reached its end
scrollingUp: emitted when a scroll event was fired and the element was scrolling up
scrollingDown: emitted when a scroll event was fired and the element was scrolling down

All these events do not have a payload.

Limitations

The, probably, most annoying problem is that if the viewport changes the directives do not emit a new event with updated values so you will have to wait next time the use scrolls. Pay special attention when using it with tablets/phones that can change screen orientation.

Scroll events are always fired for every direction, e.g.: when scrolling up horizontal scroll events are also emitted along with vertical scroll events.

I didn't write any tests because I'm lazy and UI tests are annoying to write, maybe one day I'll take the time to test the actual calculations and services.