1 # 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).
5 An adaptation of the Mootools Scrollspy (http://davidwalsh.name/mootools-scrollspy) plugin for jQuery
7 (c) 2011 Samuel Alexander (https://github.com/sxalexander/jquery-scrollspy)
11 Released under The MIT License.
15 ScrollSpy is a simple jQuery plugin for firing events based on where the user has scrolled to in a page.
19 https://github.com/softwarespot/jquery-scrollspy
23 Hosted at GitHub; browse at:
25 https://github.com/softwarespot/jquery-scrollspy/tree/master
29 git://github.com/softwarespot/jquery-scrollspy.git
33 1. Insert the necessary elements in to your document's `<head>` section, e.g.:
36 <script src="jquery.min.js"></script>
37 <script src="jquery.scrollspy.min.js"></script>
40 2. Initialise ScrollSpy once the DOM has been loaded:
48 $('#sticky-navigation').scrollspy({
49 min: $nav.offset().top,
50 onEnter: function(element, position) {
51 $nav.addClass('fixed');
53 onLeave: function(element, position) {
54 $nav.removeClass('fixed');
62 Check out the /examples for more info !
66 ScrollSpy function signature:
68 $('container').scrollspy(options, action)
71 Default options for ScrollSpy:
73 // default options for ScrollSpy
75 // the offset to be applied to the left and top positions of the container
78 // the element to apply the 'scrolling' event to (default window)
81 // the maximum value of the X or Y coordinate, depending on mode the selected
84 // the maximum value of the X or Y coordinate, depending on mode the selected
87 // whether to listen to the X (horizontal) or Y (vertical) scrolling
90 // namespace to append to the 'scroll' event
91 namespace: 'scrollspy',
93 // call the following callback function every time the user enters the min / max zone
96 // call the following callback function every time the user leaves the min / max zone
99 // call the following callback function every time the user leaves the top zone
102 // call the following callback function every time the user leaves the bottom zone
105 // call the following callback function on each scroll event within the min and max parameters
108 // call the following callback function on each scroll event when the element is inside the viewable view port
113 Events are triggered by ScrollSpy are:
115 scrollTick: Fires on each scroll event within the min and max parameters:
116 position: an object with the current X and Y position.
117 inside: a Boolean value for whether or not the user is within the min and max parameters
118 enters: the number of times the min / max has been entered.
119 leaves: the number of times the min / max has been left.
121 scrollEnter: Fires every time the user enters the min / max zone:
122 position: an object with the current X and Y position.
123 enters: the number of times the min / max has been entered.
125 scrollLeave: Fires every time the user leaves the min / max zone:
126 position: an object with the current X and Y position.
127 leaves: the number of times the min / max has been left.
129 scrollLeaveTop: Fires every time the user leaves the top zone:
130 position: an object with the current X and Y position.
131 leaves: the number of times the min / max has been left.
133 scrollLeaveBottom: Fires every time the user leaves the bottom zone:
134 position: an object with the current X and Y position.
135 leaves: the number of times the min / max has been left.
137 scrollView: Fires every time the element is inside the viewable view port:
138 position: an object with the current X and Y position.
139 leaves: the number of times the min / max has been left.
143 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`.
145 ## A note about forking:
147 By forking this project you hereby grant permission for any commits to your fork to be
148 merged back into this repository and, with attribution, be released under the terms of
153 To contribute to the project, you will first need to install [node](https://nodejs.org) globally on your system. Once installation has completed, change the working directory to the plugin's location and run the following command:
159 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](http://jshint.com) for any errors, but will also minify the plugin.
162 Call the following command to start 'watching' for any changes to the main JavaScript file(s). This will automatically invoke JSHint and Uglify.
168 Call the following command to invoke JSHint and check that the changes meet the requirements set in .jshintrc.
174 Call the following command to invoke Uglify, which will minify the main JavaScript file(s) and output to a .min.js file respectively.
180 Call the following command to invoke both JSHint and Uglify.