5.9 KiB

Raw Blame History

NOTE: This is the latest version of ScrollSpy, which includes a ton of bug fixes and efficiency improvements. It's recommended that you use this version for now instead of the official (which hasn't been updated in a while).

jQuery-ScrollSpy

An adaptation of the Mootools Scrollspy (http://davidwalsh.name/mootools-scrollspy) plugin for jQuery

Released under The MIT License.

Description:

ScrollSpy is a simple jQuery plugin for firing events based on where the user has scrolled to in a page.

Homepage:

https://github.com/softwarespot/jquery-scrollspy

Source:

Hosted at GitHub; browse at:

https://github.com/softwarespot/jquery-scrollspy/tree/master

Or clone from:

git://github.com/softwarespot/jquery-scrollspy.git

Usage:

Insert the necessary elements in to your document's <head> section, e.g.:

    <script src="jquery.min.js"></script>
    <script src="jquery.scrollspy.min.js"></script>

Initialise ScrollSpy once the DOM has been loaded:

<script>
    $(function() {

            var $nav = $('#nav');

            $('#sticky-navigation').scrollspy({
                min: $nav.offset().top,
                onEnter: function(element, position) {
                    $nav.addClass('fixed');
                },
                onLeave: function(element, position) {
                    $nav.removeClass('fixed');
                }
            });

        });
</script>

Check out the /examples for more info !

Documentation:

ScrollSpy function signature:

    $('container').scrollspy(options, action)

Default options for ScrollSpy:

// default options for ScrollSpy
var defaults = {
    // the offset to be applied to the left and top positions of the container
    buffer: 0,

    // the element to apply the 'scrolling' event to (default window)
    container: window,

    // the maximum value of the X or Y coordinate, depending on mode the selected
    max: 0,

    // the maximum value of the X or Y coordinate, depending on mode the selected
    min: 0,

    // whether to listen to the X (horizontal) or Y (vertical) scrolling
    mode: 'vertical',

    // namespace to append to the 'scroll' event
    namespace: 'scrollspy',

    // call the following callback function every time the user enters the min / max zone
    onEnter: null,

    // call the following callback function every time the user leaves the min / max zone
    onLeave: null,

    // call the following callback function every time the user leaves the top zone
    onLeaveTop: null,

    // call the following callback function every time the user leaves the bottom zone
    onLeaveBottom: null,

    // call the following callback function on each scroll event within the min and max parameters
    onTick: null,

    // call the following callback function on each scroll event when the element is inside the viewable view port
    onView: null
};

Events are triggered by ScrollSpy are:

scrollTick: Fires on each scroll event within the min and max parameters:
    position: an object with the current X and Y position.
    inside: a Boolean value for whether or not the user is within the min and max parameters
    enters: the number of times the min / max has been entered.
    leaves: the number of times the min / max has been left.

scrollEnter: Fires every time the user enters the min / max zone:
        position: an object with the current X and Y position.
        enters: the number of times the min / max has been entered.

scrollLeave: Fires every time the user leaves the min / max zone:
        position: an object with the current X and Y position.
        leaves: the number of times the min / max has been left.

scrollLeaveTop: Fires every time the user leaves the top zone:
        position: an object with the current X and Y position.
        leaves: the number of times the min / max has been left.

scrollLeaveBottom: Fires every time the user leaves the bottom zone:
        position: an object with the current X and Y position.
        leaves: the number of times the min / max has been left.

scrollView: Fires every time the element is inside the viewable view port:
        position: an object with the current X and Y position.
        leaves: the number of times the min / max has been left.

Tidy up

To destroy ScrollSpy for a particular container, simple pass 'destroy' as the action parameter. The only options that will be honoured are container and namespace.

A note about forking:

By forking this project you hereby grant permission for any commits to your fork to be merged back into this repository and, with attribution, be released under the terms of the MIT License.

Contribute

To contribute to the project, you will first need to install node globally on your system. Once installation has completed, change the working directory to the plugin's location and run the following command:

    npm install

After installation of the local modules, you're ready to start contributing to the project. Before you submit your PR, please don't forget to call gulp, which will run against JSHint for any errors, but will also minify the plugin.

Watch

Call the following command to start 'watching' for any changes to the main JavaScript file(s). This will automatically invoke JSHint and Uglify.

    gulp watch

JSHint

Call the following command to invoke JSHint and check that the changes meet the requirements set in .jshintrc.

    gulp jshint

Uglify

Call the following command to invoke Uglify, which will minify the main JavaScript file(s) and output to a .min.js file respectively.

    gulp uglify

Build

Call the following command to invoke both JSHint and Uglify.

    gulp

5.9 KiB Raw Blame History