v10.0.0

Rewrote code for better accessibility and functionality:

- Instead of preventing default on click, script now temporarily removes id from the target element to prevent scroll jumping, then adds it back after the hashchange. This provides built in browser history and forward/backward button support.
- New approach also allows for animated scrolling on page load
- Reversed order of toggle and anchor variables for animateScroll() method
- animateScroll() now supports scrolling to a number, not just an element

Author: cferdinandi

README.md

@@ -17,24 +17,24 @@ Compiled and production-ready code can be found in the `dist` directory. The `sr
 
 ### 2. Add the markup to your HTML.
 
+Turn anchor links into Smooth Scroll links by adding the `[data-scroll]` data attribute. Give the anchor location an ID just like you normally would.
+
 ```html
 <a data-scroll href="#bazinga">Anchor Link</a>
 ...
 <span id="bazinga">Bazinga!</span>
 ```
 
-Turn anchor links into Smooth Scroll links by adding the `[data-scroll]` data attribute. Give the anchor location an ID just like you normally would.
-
 ### 3. Initialize Smooth Scroll.
 
+In the footer of your page, after the content, initialize Smooth Scroll. And that's it, you're done. Nice work!
+
 ```html
 <script>
 	smoothScroll.init();
 </script>
 ```
 
-In the footer of your page, after the content, initialize Smooth Scroll. And that's it, you're done. Nice work!
-
 
 
 ## Installing with Package Managers
@@ -49,7 +49,7 @@ You can install Smooth Scroll with your favorite package manager.
 
 ## Working with the Source Files
 
-If you would prefer, you can work with the development code in the `src` directory using the included [Gulp build system](http://gulpjs.com/). This compiles, lints, and minifies code, and runs unit tests. It's the same build system that's used by [Kraken](http://cferdinandi.github.io/kraken/), so it includes some unnecessary tasks and Sass variables but can be dropped right in to the boilerplate without any configuration.
+If you would prefer, you can work with the development code in the `src` directory using the included [Gulp build system](http://gulpjs.com/). This compiles, lints, and minifies code, and runs unit tests.
 
 ### Dependencies
 Make sure these are installed first.
@@ -82,8 +82,8 @@ smoothScroll.init({
 	selectorHeader: '[data-scroll-header]', // Selector for fixed headers (must be a valid CSS selector)
 	speed: 500, // Integer. How fast to complete the scroll in milliseconds
 	easing: 'easeInOutCubic', // Easing pattern to use
-	updateURL: true, // Boolean. Whether or not to update the URL with the anchor hash on scroll
 	offset: 0, // Integer. How far to offset the scrolling anchor location in pixels
+	scrollOnLoad: true, // Boolean. If true, animate to anchor on page load if URL has a hash
 	callback: function ( toggle, anchor ) {} // Function to run after scrolling
 });
 ```
@@ -127,22 +127,21 @@ Learn more about the different easing patterns and what they do at [easings.net]
 
 ### Override settings with data attributes
 
-Smooth Scroll also lets you override global settings on a link-by-link basis using the `[data-options]` data attribute:
+Smooth Scroll also lets you override global settings on a link-by-link basis using the `[data-options]` data attribute.
 
 ```html
 <a data-scroll
    data-options='{
 					"speed": 500,
 					"easing": "easeInOutCubic",
-					"offset": 0,
-					"updateURL": false
+					"offset": 0
 				}'
 >
 	Anchor Link
 </a>
 ```
 
-**Note:** You must use [valid JSON](http://jsonlint.com/) in order for the `data-options` feature to work.
+***Note:*** *You must use [valid JSON](http://jsonlint.com/) in order for the `data-options` feature to work. Does not support the `callback` method.*
 
 ### Use Smooth Scroll events in your own scripts
 
@@ -153,24 +152,37 @@ Animate scrolling to an anchor.
 
 ```javascript
 smoothScroll.animateScroll(
-	toggle, // Node that toggles the animation. ex. document.querySelector('#toggle')
 	anchor, // ID of the anchor to scroll to. ex. '#bazinga'
+	toggle, // Node that toggles the animation, OR an integer. ex. document.querySelector('#toggle')
 	options // Classes and callbacks. Same options as those passed into the init() function.
 );
 ```
 
 **Example 1**
 
 ```javascript
-smoothScroll.animateScroll( null, '#bazinga' );
+smoothScroll.animateScroll( '#bazinga' );
 ```
 
 **Example 2**
 
 ```javascript
 var toggle = document.querySelector('#toggle');
 var options = { speed: 1000, easing: 'easeOutCubic' };
-smoothScroll.animateScroll( toggle, '#bazinga', options );
+smoothScroll.animateScroll( '#bazinga', toggle, options );
+```
+
+**Example 3**
+
+```javascript
+smoothScroll.animateScroll( 750 );
+```
+
+#### escapeCharacters()
+Escape special characters for use with `animateScroll()`.
+
+```javascript
+var toggle = smoothScroll.escapeCharacters('#1@#%^-');
 ```
 
 #### destroy()
@@ -191,25 +203,9 @@ Add a `[data-scroll-header]` data attribute to fixed headers. Smooth Scroll will
 </nav>
 ```
 
-### Animating links to other pages
-
-Smooth Scroll does not include an option to animate scrolling to links on other pages, but you can easily add this functionality using the API.
-
-1. Do *not* add the `data-scroll` attribute to links to other pages. Treat them like normal links, and include your anchor link hash as normal.
-
-    ```html
-    <a href="some-page.html#example">
-    ```
-2. Add the following script to the footer of your page, after the `smoothScroll.init()` function.
+### Animating links to other pages [NEW in v10]
 
-    ```html
-    <script>
-        if ( window.location.hash ) {
-            var options = {}; // Any custom options you want to use would go here
-            smoothScroll.animateScroll( null, window.location.hash, options );
-        }
-    </script>
-    ```
+Smooth Scroll now supports animating anchor links to other pages. Simply make sure that `scrollOnLoad` is set to `true` (the default) and point your link to the anchor on the page as normal.
 
 
 ## Browser Compatibility
@@ -222,7 +218,9 @@ Smooth Scroll is built with modern JavaScript APIs, and uses progressive enhance
 
 ## Known Issues
 
-If the `<body>` element has been assigned a height of `100%`, Smooth Scroll is unable to properly calculate page distances and will not scroll to the right location. The `<body>` element can have a fixed, non-percentage based height (ex. `500px`), or a height of `auto`.
+- If the `<body>` element has been assigned a height of `100%`, Smooth Scroll is unable to properly calculate page distances and will not scroll to the right location. The `<body>` element can have a fixed, non-percentage based height (ex. `500px`), or a height of `auto`.
+- SmoothScroll looks for a `hash` on the `href` of the link. As a result passing in an empty hash (`#`) will not work and will jump to the top of the page.
+- Many browsers will treat `#top` the same as an empty hash (`#`), resulting in a jump to the top of the page. To animate scrolling to the top of the page, please use a different ID.
 
 
 

dist/js/smooth-scroll.js

@@ -1,6 +1,6 @@
 /*!
- * smooth-scroll v7.1.1: Animate scrolling to anchor links
- * (c) 2015 Chris Ferdinandi
+ * smooth-scroll v8.0.0: Animate scrolling to anchor links
+ * (c) 2016 Chris Ferdinandi
  * MIT License
  * http://github.com/cferdinandi/smooth-scroll
  */
@@ -22,8 +22,8 @@
 	//
 
 	var smoothScroll = {}; // Object for public APIs
-	var supports = 'querySelector' in document && 'addEventListener' in root; // Feature test
-	var settings, eventTimeout, fixedHeader, headerHeight;
+	var supports = 'querySelector' in document && 'addEventListener' in root && 'onhashchange' in root; // Feature test
+	var settings, eventTimeout, fixedHeader, headerHeight, anchor;
 
 	// Default settings
 	var defaults = {
@@ -32,7 +32,7 @@
 		speed: 500,
 		easing: 'easeInOutCubic',
 		offset: 0,
-		updateURL: true,
+		scrollOnLoad: true,
 		callback: function () {}
 	};
 
@@ -170,12 +170,18 @@
 
 	/**
 	 * Escape special characters for use with querySelector
-	 * @private
+	 * @public
 	 * @param {String} id The anchor ID to escape
 	 * @author Mathias Bynens
 	 * @link https://github.com/mathiasbynens/CSS.escape
 	 */
-	var escapeCharacters = function ( id ) {
+	smoothScroll.escapeCharacters = function ( id ) {
+
+		// Remove leading hash
+		if ( id.charAt(0) === '#' ) {
+			id = id.substr(1);
+		}
+
 		var string = String(id);
 		var length = string.length;
 		var index = -1;
@@ -237,7 +243,9 @@
 			result += '\\' + string.charAt(index);
 
 		}
-		return result;
+
+		return '#' + result;
+
 	};
 
 	/**
@@ -309,17 +317,10 @@
 	};
 
 	/**
-	 * Update the URL
-	 * @private
-	 * @param {Element} anchor The element to scroll to
-	 * @param {Boolean} url Whether or not to update the URL history
+	 * Get the height of a fixed header in pixels
+	 * @param  {Node} header The header
+	 * @return {Integer}     The header height in pixels
 	 */
-	var updateUrl = function ( anchor, url ) {
-		if ( root.history.pushState && (url || url === 'true') && root.location.protocol !== 'file:' ) {
-			root.history.pushState( null, null, [root.location.protocol, '//', root.location.host, root.location.pathname, root.location.search, anchor].join('') );
-		}
-	};
-
 	var getHeaderHeight = function ( header ) {
 		return header === null ? 0 : ( getHeight( header ) + header.offsetTop );
 	};
@@ -331,28 +332,26 @@
 	 * @param {Element} anchor The element to scroll to
 	 * @param {Object} options
 	 */
-	smoothScroll.animateScroll = function ( toggle, anchor, options ) {
+	smoothScroll.animateScroll = function ( anchor, toggle, options ) {
 
 		// Options and overrides
 		var overrides = getDataOptions( toggle ? toggle.getAttribute('data-options') : null );
 		var settings = extend( settings || defaults, options || {}, overrides ); // Merge user options with defaults
-		anchor = '#' + escapeCharacters(anchor.substr(1)); // Escape special characters and leading numbers
 
 		// Selectors and variables
-		var anchorElem = anchor === '#' ? root.document.documentElement : root.document.querySelector(anchor);
+		var isNum = Object.prototype.toString.call( anchor ) === '[object Number]' ? true : false;
+		var anchorElem = isNum ? null : root.document.querySelector(anchor);
+		if ( !isNum && !anchorElem ) return;
 		var startLocation = root.pageYOffset; // Current location on the page
 		if ( !fixedHeader ) { fixedHeader = root.document.querySelector( settings.selectorHeader ); }  // Get the fixed header if not already set
 		if ( !headerHeight ) { headerHeight = getHeaderHeight( fixedHeader ); } // Get the height of a fixed header if one exists and not already set
-		var endLocation = getEndLocation( anchorElem, headerHeight, parseInt(settings.offset, 10) ); // Scroll to location
+		var endLocation = isNum ? anchor : getEndLocation( anchorElem, headerHeight, parseInt(settings.offset, 10) ); // Location to scroll to
 		var animationInterval; // interval timer
 		var distance = endLocation - startLocation; // distance to travel
 		var documentHeight = getDocumentHeight();
 		var timeLapsed = 0;
 		var percentage, position;
 
-		// Update URL
-		updateUrl(anchor, settings.updateURL);
-
 		/**
 		 * Stop the scroll animation when it reaches its target (or the bottom/top of page)
 		 * @private
@@ -364,8 +363,10 @@
 			var currentLocation = root.pageYOffset;
 			if ( position == endLocation || currentLocation == endLocation || ( (root.innerHeight + currentLocation) >= documentHeight ) ) {
 				clearInterval(animationInterval);
-				anchorElem.focus();
-				settings.callback( toggle, anchor ); // Run callbacks after animation complete
+				if ( anchorElem ) {
+					anchorElem.focus();
+				}
+				settings.callback( anchor, toggle ); // Run callbacks after animation complete
 			}
 		};
 
@@ -404,24 +405,65 @@
 	};
 
 	/**
-	 * If smooth scroll element clicked, animate scroll
+	 * Handle has change event
+	 * @private
+	 */
+	var hashChangeHandler = function () {
+
+		// Get hash from URL
+		var hash = root.location.hash;
+
+		// If anchor target is cached, reset it's ID
+		if ( anchor ) {
+			anchor.id = anchor.getAttribute( 'data-scroll-id' );
+			anchor = null;
+		}
+
+		// If there's a URL hash, animate scrolling to the matching ID
+		if ( !hash ) return;
+		hash = smoothScroll.escapeCharacters( hash ); // Escape special characters and leading numbers
+		var toggle = document.querySelector( settings.select + '[href*="' + hash + '"]');
+		smoothScroll.animateScroll( hash, toggle, settings); // Animate scroll
+
+	};
+
+	/**
+	 * Handle toggle click events
 	 * @private
+	 * @param {Event} event
 	 */
-	var eventHandler = function (event) {
+	var clickHandler = function (event) {
+
+		// Check if event target is a smooth scroll link and has a hash
 		var toggle = getClosest( event.target, settings.selector );
-		if ( toggle && toggle.tagName.toLowerCase() === 'a' ) {
-			event.preventDefault(); // Prevent default click event
-			smoothScroll.animateScroll( toggle, toggle.hash, settings); // Animate scroll
+		if ( !toggle || !toggle.hash ) return;
+
+		// Escape the hash characters
+		var hash = smoothScroll.escapeCharacters( toggle.hash ); // Escape special characters and leading numbers
+
+		// If hash is already active, animate immediately (no hash change will fire)
+		if ( hash === ( root.location.hash || '#top' ) ) {
+			smoothScroll.animateScroll( hash, toggle, settings);
+			return;
+		}
+
+		// Get the anchor target
+		anchor = document.querySelector( hash );
+
+		// If anchor exists, save the ID as a data attribute and remove it (prevents scroll jump)
+		if ( anchor ) {
+			anchor.setAttribute( 'data-scroll-id', anchor.id );
+			anchor.id = '';
 		}
+
 	};
 
 	/**
-	 * On window scroll and resize, only run events at a rate of 15fps for better performance
+	 * On window resize, only run events at a rate of 15fps for better performance
 	 * @private
-	 * @param  {Function} eventTimeout Timeout function
-	 * @param  {Object} settings
+	 * @param  {Event} event
 	 */
-	var eventThrottler = function (event) {
+	var resizeThrottler = function (event) {
 		if ( !eventTimeout ) {
 			eventTimeout = setTimeout(function() {
 				eventTimeout = null; // Reset timeout
@@ -440,14 +482,16 @@
 		if ( !settings ) return;
 
 		// Remove event listeners
-		root.document.removeEventListener( 'click', eventHandler, false );
-		root.removeEventListener( 'resize', eventThrottler, false );
+		document.removeEventListener( 'click', clickHandler, false );
+		root.removeEventListener( 'hashchange', hashChangeHandler, false );
+		root.removeEventListener( 'resize', resizeThrottler, false );
 
-		// Reset varaibles
+		// Reset variables
 		settings = null;
 		eventTimeout = null;
 		fixedHeader = null;
 		headerHeight = null;
+		anchor = null;
 	};
 
 	/**
@@ -468,9 +512,18 @@
 		fixedHeader = root.document.querySelector( settings.selectorHeader ); // Get the fixed header
 		headerHeight = getHeaderHeight( fixedHeader );
 
-		// When a toggle is clicked, run the click handler
-		root.document.addEventListener('click', eventHandler, false );
-		if ( fixedHeader ) { root.addEventListener( 'resize', eventThrottler, false ); }
+		// Event listeners
+		document.addEventListener('click', clickHandler, false);
+		root.addEventListener('hashchange', hashChangeHandler, false);
+		if ( fixedHeader ) { root.addEventListener( 'resize', resizeThrottler, false ); }
+
+		// Scroll on load
+		if ( settings.scrollOnLoad ) {
+			setTimeout(function() {
+				window.scrollTo(0, 0);
+			}, 1);
+			hashChangeHandler();
+		}
 
 	};