README.md

Angular InViewport

A simple lightweight library for Angular that detects when an element is within the browser viewport and adds a sn-viewport--in or sn-viewport--out class to the element.

This is a simple library for Angular, implemented in the Angular Package Format v5.0.

Install

via NPM

npm i @thisissoon/angular-inviewport

via Yarn

yarn add @thisissoon/angular-inviewport

app.module.ts

import { InViewportModule } from '@thisissoon/angular-inviewport';

@NgModule({
  imports: [InViewportModule]
})
export class AppModule {}

app.server.module.ts Only required For Server Side Rendering

import { InViewportModule } from '@thisissoon/angular-inviewport';

@NgModule({
  imports: [InViewportModule.forServer()]
})
export class AppServerModule {}

Browser Support

This library makes use of the Intersection Observer API which requires a polyfill to work on some browsers.

Install the polyfill

npm i intersection-observer

Or use yarn

yarn add intersection-observer

Include the polyfill

Add this somewhere in your src/polyfills.ts file

import 'intersection-observer';

Examples

A working example can be found here.

Just using classes

app.component.html

<p class="foo" snInViewport>Amet tempor excepteur occaecat nulla.</p>

app.component.css

.foo {
  transition: transform 0.35s ease-out;
}

.foo.sn-viewport--out {
  transform: translateY(-30px);
}

.foo.sn-viewport--in {
  transform: translateY(0);
}

Using events

app.component.html

<p
  class="foo"
  [ngClass]="{highlight: highlight}"
  snInViewport
  (inViewportChange)="onInViewportChange($event)">
  Amet tempor excepteur occaecat nulla.
</p>

app.component.ts

export class AppComponent {
  highlight = false;

  onInViewportChange(inViewport: boolean) {
    this.highlight = inViewport;
  }
}

app.component.css

.highlight {
  background-color: yellow;
}

Debounce example

app.component.html

<p
  class="foo"
  snInViewport
  (inViewportChange)="onInViewportChange($event)">
  Amet tempor excepteur occaecat nulla.
</p>

app.component.ts

import { Subject } from 'rxjs';
import { debounceTime } from 'rxjs/operators';

export class AppComponent {
  inViewportChange: Subject<boolean>;

  constructor() {
    this.inViewportChange = new Subject<boolean>().pipe(debounceTime(300));

    this.inViewportChange.subscribe((inViewport: boolean) =>
      console.log(`element is in viewport: ${inViewport}`)
    );
  }

  onInViewportChange(inViewport: boolean) {
    this.inViewportChange.next(inViewport);
  }
}

Offset example

You can pass any options Intersection Observer accepts using the [inViewportOptions] property. This allows offsets to be set using the rootMargin property. This property works the same as margin property in CSS.

app.component.html

<p
  class="foo"
  snInViewport
  [inViewportOptions]="{
    rootMargin: '100px 0px 0px 0px'
  }">
  Amet tempor excepteur occaecat nulla.
</p>

Limit example

app.component.html

<p
  class="foo"
  [ngClass]="{highlight: highlight}"
  snInViewport
  (inViewportChange)="onInViewportChange($event)">
  Amet tempor excepteur occaecat nulla.
</p>

app.component.ts

import { Subject } from 'rxjs';
import { take } from 'rxjs/operators';

export class AppComponent {
  inViewportChange = new Subject;
  highlight = false;

  constructor() {
    this.inViewportChange = new Subject<boolean>().pipe(take(5));

    this.inViewportChange.subscribe((inViewport: boolean) =>
      this.highlight = inViewport;
    );
  }

  onInViewportChange(inViewport: boolean) {
    this.inViewportChange.next(inViewport);
  }
}

app.component.css

.highlight {
  background-color: yellow;
}

Development server

Run ng serve for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.

Code scaffolding

Run ng generate component component-name to generate a new component. You can also use ng generate directive|pipe|service|class|guard|interface|enum|module.

Build

Run ng build to build the project. The build artifacts will be stored in the dist/ directory. Use the -prod flag for a production build.

Server side rendering

The app can be rendered on a server before serving pages to the client. Server side rendering is achieved using Express and Angular Universal with Express running a node web server and @nguniversal/express-engine providing a template engine for Express to render the angular pages.

Run npm run build:ssr && npm run serve:ssr to build client and server bundles and run an express app which will render the angular templates before being sent to the client. Navigate to http://localhost:4000/ to view the SSR version of the app.

Running unit tests

Run ng test to execute the unit tests via Karma.

Running end-to-end tests

Run ng e2e to execute the end-to-end tests via Protractor.

Making Commits

This repo uses Commitizen CLI and Conventional Changelog to create commits and generate changelogs. Instead of running git commit run git cz and follow the prompts. Changelogs will then be generated when creating new releases by running npm run release.

Making Releases

Run npm run release to create a new release. This will use Standard Version to create a new release. Standard Version will generate / update the changelog based on commits generated using Commitizen CLI, update the version number following semantic versioning rules and then commit and tag the commit for the release. Simply run git push --follow-tags origin master.

Further help

To get more help on the Angular CLI use ng help or go check out the Angular CLI README.