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
This plugin is designed to allow manipulation on elements depending on their visibility in the browser. It gives the developer the freedom to use their own CSS or JS to determine what happens; whether it's animation or a change in state. It leverages HTML5 data-* attributes instead of classes for ease and developer clarity. Emergence.js is one of the lightest and most compatible plugins of its kind.
Reference emergence.js just before your closing </body>
tag, then simply call emergence.init
.
<script src="path/to/emergence.min.js"></script>
<script>
emergence.init();
</script>
Grab the latest code from the following locations:
- Download from Github
npm install emergence.js
bower install emergence.js
Add data-emergence="hidden"
to any element you wish to watch:
<div class="element" data-emergence="hidden"></div>
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:
.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:
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.');
}
}
});
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:
var customContainer = document.querySelector('.wrapper');
emergence.init({
container: customContainer
});
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
.
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
.
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
.
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
.
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
.
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:
emergence.engage();
If you want to disable Emergence, use the following:
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