Detect if an Ember View or Component is in the viewport @ 60FPS
This ember-cli
addon adds a simple, highly performant Ember Mixin to your app. This Mixin, when added to a View
or Component
(collectively referred to as Components
), will allow you to check if that Component
has entered the browser's viewport. By default, the Mixin uses the requestAnimationFrame
API if it detects it in your user's browser โ failing which, it fallsback to using the Ember run loop and event listeners.
- App: http://development.ember-in-viewport-demo.divshot.io/
- Source: https://github.com/poteto/ember-in-viewport-demo
Usage is simple. First, add the Mixin to your Component
:
import Ember from 'ember';
import InViewportMixin from 'ember-in-viewport';
export default Ember.Component.extend(InViewportMixin, {
// ...
});
These hooks fire once whenever the Component
enters or exits the viewport. You can handle them the same way you would handle any other native Ember hook:
export default Ember.Component.extend(InViewportMixin, {
didEnterViewport() {
console.log('entered');
},
didExitViewport() {
console.log('exited');
}
});
The didScroll
hook fires when an element enters the viewport. For example, if you scrolled down in order to move the element in the viewport, the didScroll
hook would fire and also receieve the direction as a string. You can then handle it like another hook as in the above example.
export default Ember.Component.extend(InViewportMixin, {
didScroll(direction) {
console.log(direction); // 'up' || 'down' || 'left' || 'right'
}
});
To apply an .active
class to your Component
when it enters the viewport, you can simply bind the active
class to the mixed in property viewportEntered
, like so:
export default Ember.Component.extend(InViewportMixin, {
classNameBindings: [ 'viewportEntered:active' ]
});
This hook fires whenever the Component
leaves the viewport.
The mixin comes with some options. Due to the way listeners and requestAnimationFrame
is setup, you'll have to override the options this way:
export default Ember.Component.extend(InViewportMixin, {
viewportOptionsOverride: Ember.on('didInsertElement', function() {
Ember.setProperties(this, {
viewportUseRAF : true,
viewportSpy : false,
viewportScrollSensitivity : 1,
viewportRefreshRate : 150,
viewportTolerance: {
top : 50,
bottom : 50,
left : 20,
right : 20
}
});
})
});
-
viewportUseRAF: boolean
Default: Depends on browser
As it's name suggests, if this is
true
, the Mixin will userequestAnimationFrame
instead of the Ember run loop. Unless you want to force enabling or disabling this, you won't need to override this option. -
viewportSpy: boolean
Default:
false
When
true
, the Mixin will continually watch theComponent
and re-fire hooks whenever it enters or leaves the viewport. Because this is expensive, this behaviour is opt-in. When false, the Mixin will only watch theComponent
until it enters the viewport once, and then it setsviewportEntered
totrue
(permanently), and unbinds listeners. This reduces the load on the Ember run loop and your application. -
viewportScrollSensitivity: number
Default:
1
This value determines the degree of sensitivity (in
px
) in which a DOM element is considered to have scrolled into the viewport. For example, if you setviewportScrollSensitivity
to10
, thedidScroll{...}
hooks would only fire if the scroll was greater than10px
. -
viewportRefreshRate: number
Default:
100
If
requestAnimationFrame
is not present, this value determines how often the Mixin checks your component to determine whether or not it has entered or left the viewport. The lower this number, the more often it checks, and the more load is placed on your application. Generally, you'll want this value between100
to300
, which is about the range at which people consider things to be "real-time".This value also affects how often the Mixin checks scroll direction.
-
viewportTolerance: object
Default:
{ top: 0, left: 0, bottom: 0, right: 0 }
This option determines how accurately the
Component
needs to be within the viewport for it to be considered as entered.
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: {
viewportSpy : false,
viewportUseRAF : true,
viewportScrollSensitivity : 1,
viewportRefreshRate : 100,
viewportListeners : [],
viewportTolerance: {
top : 0,
left : 0,
bottom : 0,
right : 0
}
}
};
};
git clone
this repositorynpm install
bower install
ember server
- Visit your app at http://localhost:4200.
ember test
ember test --server
ember build
For more information on using ember-cli, visit http://www.ember-cli.com/.
DockYard, Inc ยฉ 2015