Elliot Fu
Introduction
Visibility provides a set of callbacks that can be attached to any element and trigger when a specific visibility event occurs.
There are a variety of uses for attaching event's to visibility, here are some of the more common ones.
Infinite Scroll
You want to start loading more content into a container when a user is partially finished scrolling through the content
Lazy Loading Images
You want to start loading an image just before it is visible to a user
Reactive Content
You want an element to change based on how far a user has scrolled
Sticky Headers
You want an element to fix itself to the viewport when it is passed, and return to its original static position afterwards
Event Tracking
You want to attach analytics events that match a users engagement with content, for example, to log to Google Analytics when a blog post is 30% read.
Examples
Infinite Scroll
As an alternative to pagination you can use onBottomVisible to load content automatically when the bottom of a container is reached.
$('.infinite.example .demo.segment')
.visibility({
once: false,
// update size when new content loads
observeChanges: true,
// load content on bottom edge visible
onBottomVisible: function() {
// loads a max of 5 times
window.loadFakeContent();
}
})
;
Infinite Scroll Example
Adding more content...
Lazy Loading Images
Visibility includes several shortcuts for setting up common visibility events. Using the setting type: 'image' will automatically attach events to an images topVisible to load the contents of data-src as src.
You can specify a placeholder image as the current src to make sure content doesn't jump when an image loads, or you can specify no placeholder and have the image appear.
By default images will appear without animation, however you can also specify a named transition, and a duration that should be used for animating the image into view
$('.demo.items .image img')
.visibility({
type : 'image',
transition : 'fade in',
duration : 1000
})
;
Helen Troy
Jenny Hess
Veronika Ossi
Stevie
Steve Jobes
Ade
Chris
Joe Henderson
Laura
Gradual Changes
Each callback receives all calculated values as its first parameter, allowing you to adjust an element using
$('.changing.example .demo.segment')
.visibility({
once : false,
continuous : true,
onPassing : function(calculations) {
var newColor = 'rgba(0, 0, 0, ' + calculations.percentagePassed +')';
$(this)
.css('background-color', newColor)
;
}
})
;
Fixing Content To Viewport
Visibility provides a lightweight method for sticking content to a page's viewport. Using type: fixed will add the class fixed after an element is passed in the viewport. Using this class name you can assign special layout conditions to an item once it is passed.
In this example, when an element is passed we fix it to the viewport, add a background color and box shadow so that it can float above other content. We also show an adjacent placeholder element which makes sure that content stays offset the same as if the menu was still in content flow
$('.overlay.example .overlay')
.visibility({
offset : 55, // fix at 55px from top of page (space for nav menu)
type : 'fixed'
})
;
.visibility.example .overlay {
padding: 0em;
box-shadow: 0px 0px 0px rgba(0, 0, 0, 0);
transition: all 0.5s ease;
background: transparent;
}
.visibility.example .fixed.overlay + .placeholder {
display: none;
}
/* fixed */
.visibility.example .fixed.overlay {
position: fixed;
background-color: #FFFFFF;
padding: 1em;
box-shadow: 0px 0px 6px rgba(0, 0, 0, 0.2);
z-index: 10;
}
.visibility.example .fixed.overlay + .placeholder {
display: block;
height: 28px;
}
Usage
How To Use
Visibility provides a set of callbacks which can be used to attach events to an element's position on screen.
Each scroll change will trigger an animation frame request that will fire callbacks for an element.
// some example callbacks
$('.demo.segment')
.visibility({
onTopVisible: function(calculations) {
// top is on screen
},
onTopPassed: function(calculations) {
// top of element passed
},
onUpdate: function(calculations) {
// do something whenever calculations adjust
updateTable(calculations);
}
})
;
| Calculation | Value |
|---|---|
| pixelsPassed | |
| percentagePassed | |
| fits | |
| width | |
| height | |
| visible | |
| hidden | |
| passing | |
| topVisible | |
| bottomVisible | |
| topPassed | |
| bottomPassed |
Changing Callback Frequency
Visibility's default settings will only have each callback occur the first time which the conditions are met. On subsequent occurences the event will not fire.
Setting continuous: true will make the callback fire anytime the callback contitions are met. So for example if you set a "top visible" callback, this callback will fire with each change in scroll when the top is visible on the page.
Setting once: false will make the callback fire each time a callback becomes true. So, using the same "top visible" example, the callback will fire each time the top of an element is passed. Even if you scroll back up and pass the element again
Event Log
Callbacks
Callbacks are separated into two categories. Standard events will occur the first animation frame where the conditions evaluated to true.
Standard Events
| Event | Occurs | Pseudocode |
|---|---|---|
| onTopVisible | Element's top edge has passed bottom of screen |
screen.bottom >= element.top
|
| onTopPassed | Element's top edge has passed top of the screen |
screen.top >= element.top
|
| onBottomVisible | Element's bottom edge has passed bottom of screen |
screen.bottom >= element.top
|
| onPassing | Any part of an element is visible on screen |
screen.bottom >= element.top && screen.top < element.bottom
|
| onBottomPassed | Element's bottom edge has passed top of screen |
screen.top >= element.bottom
|
Grouped Events
onPassed allows you to specify a collection of callbacks that occur after different percentages of an element are passed
| Event | Occurs | Example |
|---|---|---|
| onPassed {} | A percentage of an element's content has been passed |
onPassed: {
40: function() {
// do something at 40%
},
80: function() {
// do something at 80%
}
}
|
Reverse Events
Reverse events will occur under the same conditions but as a user scrolls back up the page.
| Event | Occurs | Pseudocode |
|---|---|---|
| onTopVisibleReverse | Element's top edge has not passed bottom of screen |
screen.bottom >= element.top
|
| onTopPassedReverse | Element's top edge has not passed top of the screen |
screen.top >= element.top
|
| onBottomVisibleReverse | Element's bottom edge has not passed bottom of screen |
screen.bottom >= element.top
|
| onPassingReverse | Element's top has not passed top of screen but bottom has |
screen.bottom >= element.top && screen.top < element.bottom
|
| onBottomPassedReverse | Element's bottom edge has not passed top of screen |
screen.top >= element.bottom
|
Visibility Settings
Settings to configure visibility behavior
| Setting | Default | Description |
|---|---|---|
| once | true | When set to false a callback will occur each time an element passes the threshold for a condition. |
| continuous | false | When set to true a callback will occur anytime an element passes a condition not just immediately after the threshold is met. |
| type | false | Set to image to load images when on scren. Set to fixed to add class name fixed when passed. |
| type | false | Set to image to load images when on scren. Set to fixed to add class name fixed when passed. |
| initialCheck | true | Whether visibility conditions should be checked immediately on init |
| offset | 0 | Value that context scrollTop should be adjusted in pixels. Useful for making content appear below content fixed to the page. |
| includeMargin | false | Whether element calculations should include its margin |
| throttle | false | When set to an integer, scroll position will be debounced using this ms value. false will debounce with requestAnimationFrame. |
| observeChanges | true | Whether to automatically refresh content when changes are made to the element's DOM subtree |
| transition | false | When using type: image allows you to specify transition when showing a loaded image |
| duration | 1000 | When using type: image allows you to specify transition duration |
Visibility Callbacks
Callbacks that occur on named visibility events
| Context | Description | |
|---|---|---|
| onTopVisible | $element | Element's top edge has passed bottom of screen |
| onTopPassed | $element | Element's top edge has passed top of the screen |
| onBottomVisible | $element | Element's bottom edge has passed bottom of screen |
| onPassing | $element | Any part of an element is visible on screen |
| onBottomPassed | $element | Element's bottom edge has passed top of screen |
| onTopVisibleReverse | $element | Element's top edge has not passed bottom of screen |
| onTopPassedReverse | $element | Element's top edge has not passed top of the screen |
| onBottomVisibleReverse | $element | Element's bottom edge has not passed bottom of screen |
| onPassingReverse | $element | Element's top has not passed top of screen but bottom has |
| onBottomPassedReverse | $element | Element's bottom edge has not passed top of screen |
Utility Callbacks
Callbacks that occur on named visibility events
| Context | Description | |
|---|---|---|
| onUpdate(calculations) | $element | Occurs each time an elements calculations are updated |
| onRefresh | $element | Occurs whenever element's visibility is refreshed |
DOM Settings
DOM settings specify how this module should interface with the DOM
| Setting | Default | Description |
|---|---|---|
| namespace | visibility | Event namespace. Makes sure module teardown does not effect other events attached to an element. |
| className |
className : {
fixed : 'fixed',
}
|
Class names used to attach style to state |
Debug Settings
Debug settings controls debug output to the console
| Setting | Default | Description |
|---|---|---|
| name | Visibility | Name used in debug logs |
| debug | False | Provides standard debug output to console |
| performance | True | Provides standard debug output to console |
| verbose | True | Provides ancillary debug output to console |
| errors |
error : {
method : 'The method you called is not defined.',
}
|
|