Detect element visibility in the browser

Emergence.js is a lightweight, high-performance JS plugin for detecting and manipulating elements in the browser.

*


- Dependancy-free
- IE8+ and all modern browsers
- 1KB minified and gzipped
*
*
tag, then simply call emergence.init.
``html`
Grab the latest code from the following locations:
- Download from Github
- npm install emergence.jsbower install emergence.js
-
*
Add data-emergence="hidden" to any element you wish to watch:
`html`
When the element becomes visible within the viewport, the attribute will change to data-emergence="visible". Now you can leverage CSS, for example, to animate the element:
`css`
.element[data-emergence=hidden] {
/ Hidden state /
}
.element[data-emergence=visible] {
/ Visible state /
}
*
Emergence.js has a number of options you can customize. Below are the defaults:
`javascript`
emergence.init({
container: window,
reset: true,
handheld: true,
throttle: 250,
elemCushion: 0.15,
offsetTop: 0,
offsetRight: 0,
offsetBottom: 0,
offsetLeft: 0,
callback: function(element, state) {
if (state === 'visible') {
console.log('Element is visible.');
} else if (state === 'reset') {
console.log('Element is hidden with reset.');
} else if (state === 'noreset') {
console.log('Element is hidden with NO reset.');
}
}
});
#### container
By default, the visibility of elements will be determined by the window's viewport dimensions and X/Y scroll position (when set to window). However, it's possible to change it to a custom container. For example:
`javascript
var customContainer = document.querySelector('.wrapper');
emergence.init({
container: customContainer
});
`
#### throttle
Throttle is a method that prevents performance issues associated with scroll and resize events. The throttle will create a small timeout and steadily check element visibility every set amount of milliseconds during the event. The default is 250.
#### reset
Determines whether the data-attribute state will reset after it's been revealed. Set reset to false if you wish for the element to stay in its revealed state even after leaving the viewport. The default is true.
#### handheld
Emergence will do a check for most handheld device models such as phones and tablets. When set to false, the plugin will not run on those devices. The default is true.
#### elemCushion
The element cushion will determine how much of the element needs to be within the viewport to count as "visible". A value of 0.5 would equate to 50% of the element needing to be visible. The default is 0.15.
#### offsetTop, offsetRight, offsetBottom, offsetLeft
Provide an offset (in pixels) on any edge of the viewport. This is useful if you have a fixed component such as a header, for which you can offset the same value as the height of the header. A value of 100 applied to offsetTop will mean elements will only count as visible when they are greater than 100 pixels from the top of the viewport. The default for all is 0.
#### callback
Useful for providing callbacks to determine when an element is visible, hidden and reset. The possible states are visible, reset, and noreset.
*
If you want to refire visibility checks outside of the load, scroll and resize events already baked into the plugin, use the following:
`javascript`
emergence.engage();
If you want to disable Emergence, use the following:
`javascript``
emergence.disengage();
*
Emergence.js is dependent on the following browser APIs:
- querySelectorAll
- For support in IE8, ensure standards mode
*
Issues can be resolved quicker if they are descriptive and include both a minimal test case and a set of steps to reproduce.
While new features are welcome, any contributions that can fix bugs, maximize compatibility, and improve performance are preferred.
*
- 1.1.2
- Added handheld detection for Kindle Fire and PlayBook
- Updated comments
- Updated npm packages
- Optimized animations on demo
- Optimized responsive styles on demo
- Added release history to README.md