ngx-stickybits

Angular sticky directive using Stickybits, a lightweight alternative to position: sticky polyfills.

⏰ The project is still a Work-In-Progress and may be subject to major changes.

Installation
Configuration
Usage
Browser Compatibility
Quirks
Demo application
Road map
Contribution

Installation

To add ngx-stickybits library to your package.json use the following command.

npm install ngx-stickybits --save

Configuration

Import StickybitsModule to your angular module to be able to use stickybits directive.

import { NgModule } from '@angular/core';
+ import { StickybitsModule } from 'ngx-stickybits';

import { AppComponent } from './app.component';

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

Usage

ngx-stickybits provides the stickybits directive to apply on element you want to be sticky.

<div class="some-stickybits-parent">
  <div class="some-stickybits-element" stickybits>
    I am a sticky element
  </div>
</div>

Input Properties

stickybits directive can be customized using the following properties:

Property	Type	Default	Description
@Input() noStyles	boolean	`false`	To use StickyBits without inline styles except for `position: sticky` or `position: fixed`
@Input() scrollEl	Element \| string	`window`	Desired scrolling element or DOM query selector
@Input() parentClass	string	'sticky-parent'	Applied CSS class on the parent of the sticky element
@Input() stickyChangeClass	string	'sticky--change'	Applied CSS class after the element is sticky for a certain duration of scroll - By default this duration of scrolling is the height of the sticky element
@Input() stickyChangeNumber	number	sticky element height	Scroll duration for when `.sticky--change` is added can be modified by providing a number for this option
@Input() stickyClass	string	'sticky'	Applied CSS class on element when it is sticky
@Input() stuckClass	string	'stuck'	Applied CSS class on element when it is stuck
@Input() stickyOffset	number	0	Desired offset from the top of the viewport to which the element will stick
@Input() useFixed	boolean	`false`	Enforce `position: fixed` instead of using `position: sticky`
@Input() useGetBoundingClientRect	boolean	`false`	Do not use `offsetTop` provide the optional boolean `useGetBoundingClientRect` - This feature is optimal when dealing with things like CSS calc which can throw off `offsetTop` calculations
@Input() useStickyClasses	boolean	`true`	Add/remove classes from element according to it's sticky state (see details below) — This is expensive for the browser, it is better if can be avoided and remain `false`
@Input() verticalPosition	'top' \| 'bottom'	'top'	Stick element to the top/bottom of the viewport when vertically scrolled to
@Output() sticky	EventEmitter<boolean>		Emits `true` when element becomes sticky and `false` when it becomes unsticky
@Output() stuck	EventEmitter<boolean>		Emits `true` when element becomes stuck and `false` when it becomes unstuck

⚠️ Right now events are only emitted when useStickyClasses is set to true as those are based on CSS class detection with MutationObserver which offers better browser compatibility then IntersectionObserver althought refactoring might be reconsidered in the future.

When useStickyClasses is set to true, the following CSS classes will be applied on elements (can be can be overwritten):

sticky if the selected element is sticky
stuck if the selected element is stopped at the bottom of its parent
sticky--change if the selected element is scrolling within the height of the sticky element (before it get sticky)
sticky-parent so that styles can easily be added to the parent of a sticky element

Browser Compatibility

Stickybits works in modern browsers like a charm, when it turns to Internet Explorer it is often a total different story! Althought it tend to support IE 9 and above by using position: fixed the result not always what is expected. Please file and issue with browser compatibility quirks here.

Quirks

I won't lie to you, getting an element sticky has always been a hard and painful task! Although Stickybits makes it easier it is not always magic and sometime require some twists to make it works as desired. This section is dedicated to quirks and how to resolve common problematic behaviors using stickybits directive.

verticalPosition = 'bottom'

Setting [verticalPosition]="'bottom'" won't work out of the box, easiest way to fix it is to put the sticky parent element with display: flex and set the sticky element with align-self: flex-end.

Demo Application

Demo application is available @ https://jfcere.github.io/ngx-stickybits and its source code can be found inside the demo directory.

The following commands will clone the repository, install npm dependencies and serve the application @ http://localhost:4200

git clone https://github.com/jfcere/ngx-stickybits.git
npm install
ng serve

Road map

Here is the list of tasks that will be done on this library in a near future ...

~~Publish demo on github pages~~
~~Improve documentation~~
Add CircleCI integration
Add unit tests
Add Module configuration (CSS classes, useFixed, noStyles, ...)

Contribution

Contributions are always welcome, just make sure that ...

Your code style matches with the rest of the project
Unit tests pass
Linter passes

License

I do not own rights for Stickybits and all the credits belong to them — see DollarShaveClub/Stickybits for details.

This package is licensed under MIT license — see LICENSE file for details.

jfcere/ngx-stickybits