ScrllWatch

Easily add lazy loading, infinite scrolling, or any other dynamic interaction based on scroll position.

Old 1.2.0 Docs

Downloads

Installation

Features

Basic Usage

Include the library on your page.

<script src="ScrollWatch.js"></script>

Create a new ScrollWatch instance and pass in an options object with an onElementInView callback. By default, ScrollWatch will fire your callback when any elements with a data-scroll-watch attribute come into view. Check out the API section below for all options.

var sw = new ScrollWatch({
	onElementInView: function(data) {
		console.log(data.el, '...is now in view');
	}
});

API

Instantiation

You can create as many instances of ScrollWatch as you need. The constructor accepts an options object, allowing you to customize your instance. Save a reference to the new instance if you want to call any of the public methods at a later time.

var sw = new ScrollWatch({
	/* options */
})

Options

Below are all of the options you can pass to ScrollWatch and their default values:

container: window.document.documentElement
A selector or DOM node that contains the elements you want to watch. Remember, you can have multiple instances and watch nested containers.
watch: '[data-scroll-watch]'
A selector for the element(s) you want to watch.
watchOnce: true
True to stop watching the element after it comes into view the first time. False to watch the element forever.
ignoreClass: 'scroll-watch-ignore'
When watchOnce is set to true, this class will be applied to elements that have come into view.
inViewClass: 'scroll-watch-in-view'
Class applied to elements that are in view.
debounce: false
True to debounce scroll and resize events, false to throttle.
debounceTriggerLeading: false
True to process scroll and resize events on the leading edge, false for the trailing edge.
scrollDebounce: 250
Number of milliseconds to wait since the last scroll event before processing the event.
resizeDebounce: 250
Number of milliseconds to wait since the last resize event before processing the event.
scrollThrottle: 250
Number of milliseconds to wait between processing scroll events.
resizeThrottle: 250
Number of milliseconds to wait between processing resize events.
watchOffsetXLeft: 0
Number of pixels to offset the left side of the horizontal scroll area when processing elements. For example, if a watched element is 5 pixels to the left of the fold, it will be considered in view if watchOffset is > 5 pixels.
watchOffsetXRight: 0
Number of pixels to offset the right side of the horizontal scroll area when processing elements. For example, if a watched element is 5 pixels to the right of the fold, it will be considered in view if watchOffset is > 5 pixels.
watchOffsetYTop: 0
Number of pixels to offset the top of the vertical scroll area when processing elements. For example, if a watched element is 5 pixels above the fold, it will be considered in view if watchOffset is > 5 pixels.
watchOffsetYBottom: 0
Number of pixels to offset the bottom of the vertical scroll area when processing elements. For example, if a watched element is 5 pixels below the fold, it will be considered in view if watchOffset is > 5 pixels.
onElementInView: function(obj){}
Callback for when an element comes into view. A data object will be passed into the callback with the following properties:
eventType
Value of 'scroll', 'resize', 'refresh' or 'scrollwatchinit' if the element is in view on instantiation.
el
The element being watched.
direction
Value of 'up', 'down', 'right' or 'left' for an eventType of 'scroll', otherwise undefined.
onElementOutOfView: function(obj){}
Callback for when an element goes out of view. The same data object will be passed in as described in onElementInView.
infiniteScroll: false
Whether or not to turn on infinite scroll watching. If true, callbacks will be fired when the container reaches the end.
infiniteOffset: 0
Similar to watchOffset, number of pixels to offset what is considered the end of the container.
onInfiniteYInView: function(obj){}
Callback for when container has reached its vertical end. A data object will be passed into the callback with the following properties:
eventType
Value of 'scroll', 'resize', 'refresh' or 'scrollwatchinit' if the container is at its end on instantiation.
direction
Value of 'up', 'down', 'right' or 'left' for an eventType of 'scroll', otherwise undefined.
onInfiniteXInView: function(obj){}
Callback for when container has reached its horizontal end. The same data object will be passed in as described in onInfiniteYInView.

Methods

Below are the public methods available on each ScrollWatch instance:

refresh()
Rechecks the dom for new elements to watch. Call this after injecting new content into the DOM that matches an existing watch you have setup.
destroy()
Destroy the instance of ScrollWatch.
updateWatchOffsetXLeft(offset)
Update the value for the watchOffsetXLeft option.
updateWatchOffsetXRight(offset)
Update the value for the watchOffsetXRight option.
updateWatchOffsetYTop(offset)
Update the value for the watchOffsetYTop option.
updateWatchOffsetYBottom(offset)
Update the value for the watchOffsetYBottom option.
pauseInfiniteScroll()
Pause infinite scroll watching.
resumeInfiniteScroll()
Resume infinite scroll watching.

Demos

ScrollWatch is only limited by your imagination! Below are some demos that outline the basic building blocks of a ScrollWatch interaction.

Fades in elements when they come into view the first time.

See the Pen Fade In Elements Once by Evan Dull (@edull24) on CodePen.

Fades in elements when they come into view every time.

See the Pen Fade In Elements Every Time by Evan Dull (@edull24) on CodePen.

Fades in elements in a container other than "window" when they come into view the first time.

See the Pen ScrollWatch.js Demo: Nested Watching by Evan Dull (@edull24) on CodePen.

Injects new elements into the page when you get 200px from the bottom of the page.

See the Pen ScrollWatch.js Demo: Infinite Scrolling by Evan Dull (@edull24) on CodePen.