ScrollWatch
jQuery plugin for determining active sections on the page based on scrolling.
Contents
Features
- determining active section(s)
- mapping a class to a list of elements (e.g. menu items)
- many options, including multiple modes of resolution
- works with zoom
Requirements
jQuery 1.9.0 or newer
Browser support
Tested in Mozilla Firefox, Google Chrome, Safari, Opera and MSIE 7+.
Usage
The plugin provides two jQuery methods:
Note
If the sections are inside a custom scrollable element, that element must have
position: relative, absolute or fixed.
$(sections).scrollWatch(callback[, options])
Attaches a watcher to the given sections. The callback is then invoked when the focus changes, according to options.
sections- selector or an array of elements that represent all the possible sectionscallback- function to invoke when the focus changesoptions- object with various settings (see list far below)
Callback arguments
$('div.section').scrollWatch(function (focus, view, watcher) {
// do something with the current focus
});Object|Object[] focus- the current focus, an object with the following properties:(ifresolutionModeisnone, it will be an array of those objectsindex- section number (0-based)intersection-nullor[y1, y2]section- DOM element of the section
Object view- the current view, an object with the following properties:top- top coordinate of the viewbottom- bottom coordinate of the view
Shira.ScrollWatch.Watcher watcher- instance of the current watcher
$(sections).scrollWatchMapTo(items[, activeClass, options])
Attaches a watcher to the given sections and maps the current focus to the respective item using the specified active class.
sections- selector or an array of elements that represent all the possible sectionsitems- selector or an array of elements to map the "active class" toactiveClass- class name to add to the active item (defaults to"active")options- object with various settings (see list far below)
Example
$('div.section').scrollWatchMapTo('#menu > li');List of supported options
| Option | Default | Description |
|---|---|---|
scroller |
null |
DOM element to watch for scrolling events. It must be an If no element is given the first found scrollable
offset parent or |
resolutionMode |
"height" |
Determines how the active section is chosen, one of:
|
viewMarginTop |
0 |
Height of an area at the top of the view to be excluded. |
viewMarginBottom |
0 |
Height of an area at the bottom of the view to be excluded. |
stickyOffsetTop |
5 |
Height of an area at the top of the scroller that, if intersected by the top of the view, forces the first section to be active regardless of other conditions. |
stickyOffsetBottom |
5 |
Height of an area at the bottom of the scroller that, if intersected by the bottom of the view, forces the last section to be active regardless of other conditions. |
clamp |
false |
When enabled, the space between two sections is considered a part of the first section. Useful when there are large gaps between sections. |
throttle |
true |
When enabled, the callback is invoked only when the active section changes When disabled, the callback is invoked on every pulse (e.g. on scroll and resize). This option has no effect when |
Options specific to resolutionMode = height
| Option | Default | Description |
|---|---|---|
topDownWeight |
0 |
Extra focus height added to the section if it precedes the other. This can be used to prefer earlier sections to later ones. |
Options for resolutionMode = focus-line
| Option | Default | Description |
|---|---|---|
focusRatio |
0.3819.. |
Percentage of the view height that determines position of the focus line. |
focusOffset |
0 |
Offset added to position of the focus line position
after Set |
debugFocusLine |
false |
When enabled, position of the focus line will be displayed when scrolling Intended for debugging purposes. |
Options for resolutionMode = custom
| Option | Default | Description |
|---|---|---|
resolver |
none (required) | Function to invoke when a focus candidate resolution is needed. It must choose and return a single focus object. The following arguments are passed to the function:
|