Menu

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 events 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.

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.

The following examples use sticky columns to help display data alongside each example. Please consult the sticky documentation for usage examples.
// 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
onScreen
offScreen
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 conditions 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

Clear
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
onOnScreen Any part of element is in current scroll viewport
screen.bottom >= element.top && screen.bottom <= element.bottom
onOffScreen No part of element is in current scroll viewport
screen.bottom <= element.top || screen.top >= element.bottom
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 or pixels of an element are passed

Event Occurs Example
onPassed {} A distance from the top of an element's content has been passed, either as a percentage or in pixels
onPassed: { 40: function() { // do something when having passed 40 pixels. }, '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

Behaviors

Visibility includes several useful behaviors for interacting with the component

Behavior Usage
disable callbacks Disable callbacks temporarily. This is useful if you need to adjust scroll position and do not want to trigger callbacks during the position change.
enable callbacks Re-enable callbacks
is on screen Returns whether element is on screen
is off screen Returns whether element is off screen
get pixels passed Returns number of pixels passed in current element from top of element
get element calculations Returns element calculations as object
get screen calculations Returns screen calculations as object
get screen size Returns screen size as object

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 }) ;

Elliot Fu

Add Friend
View

Helen Troy

Add Friend
View

Jenny Hess

Add Friend
View

Veronika Ossi

Add Friend
View

Stevie

Add Friend
View

Steve Jobes

Add Friend
View

Ade

Add Friend
View

Chris

Add Friend
View

Joe Henderson

Add Friend
View

Laura

Add Friend
View

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.

Using the special visibility type fixed will automatically create a placeholder element, which will be shown or hidden after an element is passed, to ensure that the page's position does not change when the element is "fixed" and removed from normal layout flow.

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

You may need to adjust your fixed content's z-index to ensure it appears above other page content.
$('.overlay.example .overlay') .visibility({ type : 'fixed', offset : 15 // give some space from top of screen }) ;
.visibility.example .overlay { background-color: #FFFFFF; padding: 0em; box-shadow: 0px 0px 0px rgba(0, 0, 0, 0); transition: all 0.5s ease; background: transparent; } /* change style */ .visibility.example .fixed.overlay { position: fixed; padding: 1em; box-shadow: 0px 0px 6px rgba(0, 0, 0, 0.2); }

Settings

Functionality
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 screen. Set to fixed to add class name fixed when passed.
initialCheck true Whether visibility conditions should be checked immediately on init
context window The scroll context visibility should use.
refreshOnLoad true Whether visibility conditions should be checked on window load. This ensures that after images load content positions will be updated correctly.
refreshOnResize true Whether visibility conditions should be checked on window resize. Useful when content resizes causes continuous changes in position
checkOnRefresh true Whether visibility conditions should be checked on calls to refresh. These calls can be triggered from either resize, load or manually calling $('.foo').visibility('refresh')
zIndex 1 Specify a z-index when using type: 'fixed'.
New in 2.2
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

Image Callbacks
New in 2.2

Callbacks that occur only when using type: 'fixed'

Context Description
onLoad img Occurs after an image has completed loading
onAllLoaded last loaded img Occurs after all img initialized at the same time have loaded.

Fixed Callbacks
New in 2.2

Callbacks that occur only when using type: 'fixed'

Context Description
onFixed $element Occurs after element has been assigned position fixed
onUnfixed $element Occurs after element has been removed from fixed position

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
silent False Silences all console output including error messages, regardless of other debug settings.
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.', }

Dimmer Message
Dimmer sub-header