search

DockYard / ember-in-viewport

Detect if an Ember View or Component is in the viewport @ 60FPS
MIT License
245 stars 91 forks source link
ember intersectionobserver viewport

readme

ember-in-viewport

Detect if an Ember View or Component is in the viewport @ 60FPS

ember-in-viewport is built and maintained by DockYard, contact us for expert Ember.js consulting.

Read the blogpost

Download count all time npm version GitHub Actions Build Status Ember Observer Score

This Ember addon adds a simple, highly performant Service or modifier to your app. This library will allow you to check if a Component or DOM element has entered the browser's viewport. By default, this uses the IntersectionObserver API if it detects it the DOM element is in your user's browser – failing which, it falls back to using requestAnimationFrame, then if not available, the Ember run loop and event listeners.

We utilize pooling techniques to reuse Intersection Observers and rAF observers in order to make your app as performant as possible and do as little works as possible.

Demo or examples

Table of Contents

Installation

ember install ember-in-viewport

Usage

Usage is simple. First, inject the service to your component and start "watching" DOM elements.

import Component from '@glimmer/component';
import { action } from '@ember/object';
import { inject as service } from '@ember/service';

export default class MyClass extends Component {
  @service inViewport

  @action
  setupInViewport() {
    const loader = document.getElementById('loader');
    const viewportTolerance = { bottom: 200 };
    const { onEnter, _onExit } = this.inViewport.watchElement(loader, { viewportTolerance });
    // pass the bound method to `onEnter` or `onExit`
    onEnter(this.didEnterViewport.bind(this));
  }

  didEnterViewport() {
    // do some other stuff
    this.infinityLoad();
  }

  willDestroy() {
    // need to manage cache yourself
    const loader = document.getElementById('loader');
    this.inViewport.stopWatching(loader);

    super.willDestroy(...arguments);
  }
}
<ul>
  <li></li>
  ...
</ul>
<div id="loader"></div>

You can also use Modifiers as well. Using modifiers cleans up the boilerplate needed and is shown in a later example.

Configuration

To use with the service based approach, simply pass in the options to watchElement as the second argument.

import Component from '@glimmer/component';
import { inject as service }  from '@ember/service';

export default class MyClass extends Component {
  @service inViewport

  @action
  setupInViewport() {
    const loader = document.getElementById('loader');

    const { onEnter, _onExit } = this.inViewport.watchElement(
      loader,
      {
        viewportTolerance: { bottom: 200 },
        intersectionThreshold: 0.25,
        scrollableArea: '#scrollable-area'
      }
    );
  }
}

Global options

You can set application wide defaults for ember-in-viewport in your app (they are still manually overridable inside of a Component). To set new defaults, just add a config object to config/environment.js, like so:

module.exports = function(environment) {
  var ENV = {
    // ...
    viewportConfig: {
      viewportUseRAF                  : true,
      viewportSpy                     : false,
      viewportListeners               : [],
      intersectionThreshold           : 0,
      scrollableArea                  : null,
      viewportTolerance: {
        top    : 0,
        left   : 0,
        bottom : 0,
        right  : 0
      }
    }
  };
};

// Note if you want to disable right and left in-viewport triggers, set these values to `Infinity`.

Modifiers

Using with Modifiers is easy.

You can either use our built in modifier {{in-viewport}} or a more verbose, but potentially more flexible generic modifier. Let's start with the former.

  1. Use {{in-viewport}} modifier on target element
  2. Ensure you have a callbacks in context for enter and/or exit
  3. options are optional - see Advanced usage (options)
<ul class="list">
  <li></li>
  <li></li>
  <div {{in-viewport onEnter=(fn this.onEnter artwork) onExit=this.onExit scrollableArea=".list"}}>
    List sentinel
  </div>
</ul>

This modifier is useful for a variety of scenarios where you need to watch a sentinel. With template only components, functionality like this is even more important! If you have logic that currently uses the did-insert modifier to start watching an element, try this one out!

If you need more than our built in modifier...

  1. Install @ember/render-modifiers
  2. Use the did-insert hook inside a component
  3. Wire up the component like so

Note - This is in lieu of a did-enter-viewport modifier, which we plan on adding in the future. Compared to the solution below, did-enter-viewport won't need a container (this) passed to it. But for now, to start using modifiers, this is the easy path.

import Component from '@glimmer/component';
import { action } from '@ember/object';
import { inject as service } from '@ember/service';

export default class MyClass extends Component {
  @service inViewport

  @action
  setupInViewport() {
    const loader = document.getElementById('loader');
    const viewportTolerance = { bottom: 200 };
    const { onEnter, _onExit } = this.inViewport.watchElement(loader, { viewportTolerance });
    onEnter(this.didEnterViewport.bind(this));
  }

  didEnterViewport() {
    // do some other stuff
    this.infinityLoad();
  }

  willDestroy() {
    // need to manage cache yourself
    const loader = document.getElementById('loader');
    this.inViewport.stopWatching(loader);

    super.willDestroy(...arguments);
  }
}
<div {{did-insert this.setupInViewport}}>
  {{yield}}
</div>

Options as the second argument to inViewport.watchElement include:

IntersectionObserver's Browser Support

Out of the box

Chrome 51 [1]
Firefox (Gecko) 55 [2]
MS Edge 15
Internet Explorer Not supported
Opera [1] 38
Safari Safari Technology Preview
Chrome for Android 59
Android Browser 56
Opera Mobile 37

Running

Running Tests

Building

For more information on using ember-cli, visit http://www.ember-cli.com/.

Legal

DockYard, Inc © 2015

@dockyard

Licensed under the MIT license

Contributors

We're grateful to these wonderful contributors who've contributed to ember-in-viewport: