Allows for easy implementation of smooth scrolling for same-page links.
Note: Version 2.0+ of this plugin requires jQuery version 1.7 or greater.
Add back button support by using a hashchange event listener. You can also include a history management plugin such as Ben Alman's BBQ for ancient browser support (IE < 8), but you'll need jQuery 1.8 or earlier. See demo/hashchange.html or demo/bbq.html for an example of how to implement.
// fn(opts) function to be called before scrolling occurs.
// fn(opts) function to be called after scrolling occurs.
// autoCoefficent: Only used when speed set to "auto".
The options object for $.fn.smoothScroll can take two additional properties: exclude and excludeWithin. The value for both of these is an array of selectors, DOM elements or jQuery objects. Default value for both is an empty array.
If you need to change any of the options after you've already called .smoothScroll(), you can do so by passing the "options" string as the first argument and an options object as the second.
The $.smoothScroll method can take one or two arguments.
If the first argument is a number or a "relative string," the document is scrolled to that position. If it's an options object, those options determine how the document (or other element) will be scrolled.
If a number or "relative string" is provided as the second argument, it will override whatever may have been set for the scrollTarget option.
The relative string syntax, introduced in version 2.1, looks like +=100px or -=50px (see below for an example).
// The jQuery set of elements you wish to scroll.
//  if null (default), $('html, body').firstScrollable() is used.
Selects the matched element(s) that are scrollable. Acts just like a DOM traversal method such as .find() or .next().
The resulting jQuery set may consist of zero, one, or multiple elements.
Selects the first matched element that is scrollable. Acts just like a DOM traversal method such as .find() or .next().
The resulting jQuery set may consist of zero or one element.
// Call $.smoothScroll if location.hash starts with "#smoothScroll"
Focus element after scrolling to it.
To determine where to scroll the page, the $.fn.smoothScroll method looks for an element with an id attribute that matches the <a> element's hash. It does not look at the element's name attribute. If you want a clicked link to scroll to a "named anchor" (e.g. <a name="foo">), you'll need to use the $.smoothScroll method instead.
The plugin's $.fn.smoothScroll and $.smoothScroll methods use the $.fn.firstScrollable DOM traversal method (also defined by this plugin) to determine which element is scrollable. If no elements are scrollable, these methods return a jQuery object containing an empty array, just like all of jQuery's other DOM traversal methods. Any further chained methods, therefore, will be called against no elements (which, in most cases, means that nothing will happen).
For code changes, please work on the "source" file: src/jquery.smooth-scroll.js.
Style conventions are noted in the jshint grunt file options and the .jscsrc file. To be sure your additions comply, run grunt lint from the command line.
If possible, please use Tim Pope's git commit message style. Multiple commits in a pull request will be squashed into a single commit. I may adjust the message for clarity, style, or grammar. I manually commit all merged PRs using the --author flag to ensure that proper authorship (yours) is maintained.