A lightweight script to animate scrolling to anchor links. View the demo.
In This Documentation
- Getting Started
- Options & Settings
- Browser Compatibility
- Contributors
- How to Contribute
- License
- Changelog
- Older Docs
<script src="js/smooth-scroll.js"></script>
<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.
<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!
Smooth Scroll includes smart defaults and works right out of the box. But if you want to customize things, it also has a robust API that provides multiple ways for you to adjust the default options and settings.
You can pass options and callbacks into Smooth Scroll through the init()
function:
smoothScroll.init({
speed: 500, // Integer. How fast to complete the scroll in milliseconds
easing: 'easeInOutCubic', // Easing pattern to use
updateURL: false, // 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
callbackBefore: function ( toggle, anchor ) {}, // Function to run before scrolling
callbackAfter: function ( toggle, anchor ) {} // Function to run after scrolling
});
Linear Moves at the same speed from start to finish.
Linear
Ease-In Gradually increases in speed.
easeInQuad
easeInCubic
easeInQuart
easeInQuint
Ease-In-Out Gradually increases in speed, peaks, and then gradually slows down.
easeInOutQuad
easeInOutCubic
easeInOutQuart
easeInOutQuint
Ease-Out Gradually decreases in speed.
easeOutQuad
easeOutCubic
easeOutQuart
easeOutQuint
Learn more about the different easing patterns and what they do at easings.net.
Smooth Scroll also lets you override global settings on a link-by-link basis using the [data-options]
data attribute:
<a data-scroll
data-options="speed: 500;
easing: easeInOutCubic;
offset: 0;
updateURL: false"
>
Anchor Link
</a>
You can also call Smooth Scroll's scroll animation events in your own scripts:
smoothScroll.animateScroll(
toggle, // Node that toggles the animation. ex. document.querySelector('#toggle')
anchor, // ID of the anchor to scroll to. ex. '#bazinga'
options, // Classes and callbacks. Same options as those passed into the init() function.
event // Optional, if a DOM event was triggered.
);
Example 1
smoothScroll.animateScroll( null, '#bazinga' );
Example 2
var toggle = document.querySelector('#toggle');
var options = { speed: 1000, easing: 'easeOutCubic' };
smoothScroll.animateScroll( toggle, '#bazinga', options );
Add a [data-scroll-header]
data attribute to fixed headers. Smooth Scroll will automatically offset scroll distances by the header height. If you have multiple fixed headers, add [data-scroll-header]
to the last one in the markup.
<nav data-scroll-header>
...
</nav>
Smooth Scroll works in all modern browsers, and IE 9 and above.
Smooth Scroll is built with modern JavaScript APIs, and uses progressive enhancement. If the JavaScript file fails to load, or if your site is viewed on older and less capable browsers, anchor links will jump the way they normally would. If you need to smooth scrolling for older browsers, download the jQuery version of Smooth Scroll on GitHub.
- Easing support contributed by Willem Liu.
- Easing functions forked from Gaëtan Renaudeau.
- URL history support contributed by Robert Pate.
- Fixed header support contributed by Arndt von Lucadou.
- Infinite loop bugs in iOS and Chrome (when zoomed) by Alex Guzman.
- IE10 rounding error fixed by Luke Siedle.
- Enhanced callback functions by Constant Meiring.
- Scroll-to-top bug for links at the bottom of the page by Jonas Havers.
In lieu of a formal style guide, take care to maintain the existing coding style. Don't forget to update the version number, the changelog (in the readme.md
file), and when applicable, the documentation.
Smooth Scroll is licensed under the MIT License.
- v4.6 - March 21, 2014
- v4.5 - March 20, 2014
- Added
offset
tooptions
- Added
- v4.4 - March 15, 2014
- v4.3 - March 5, 2014
- Added arguments to callback functions for greater versatility. 44
- v4.2 - February 27, 2014
- Fixed error for null
toggle
argument inanimateScroll
function (43).
- Fixed error for null
- v4.1 - February 27, 2014
- Converted
_defaults
to a literal object
- Converted
- v4.0 - February 21, 2014
- Better public/private method namespacing.
- Require
init()
call to run. - New API exposes additional methods for use in your own scripts.
- Better documentation.
- v3.3 - February 19, 2014
- v3.2 - February 10, 2014
- Fixes iOS infinite loop and Chrome browser zoom bugs.
- v3.1 - February 4, 2014
- Reverted to
Array.protype.foreach
loops.
- Reverted to
- v3.0 - January 28, 2014
- Switched to a data attribute for the toggle selector.
- Added namespacing to IIFE.
- Updated looping method and event listener.
- v2.19 - January 23, 2014
- v2.18 - January 23, 2014
- v2.17 - January 17, 2014
- v2.16 - January 16, 2014
- v2.15 - January 16, 2014
- v2.14 - January 15, 2014
- v2.12 - January 7, 2014
- v2.11 - January 4, 2014
- v2.10 - December 31, 2013
- v2.9 - December 9, 2013
- v2.8 - December 3, 2013
- Fixed false distance reading.
- Added linear easing as fallback when easing pattern not recognized to prevent script from failing.
- v2.7 - November 25, 2013
- Converted naming conventions back to mathmatical roots (ex.
easeInCubic
) to remain consistent with development community language.
- Converted naming conventions back to mathmatical roots (ex.
- v2.6 - November 26, 2013
- Missing character was causing certain easing functions to break.
- v2.5 - November 22, 2013
- Changed the default easing to
easeInOutNormal
.
- Changed the default easing to
- v2.4 - November 21, 2013
- Added easing support with contributions from Willem Liu and code from Gaëtan Renaudeau.
- v2.3 - August 27, 2013
- Added missing semicolons.
- Defined
animationStop
variable once, add values later. - Activated strict mode.
- Wrapped in IIFE.
- v2.2 - August 17, 2013
- Now you can set the animation speed with the
data-speed
attribute. (ex.data-speed="400"
)
- Now you can set the animation speed with the
- v2.1 - August 17, 2013
- Improvement animation function interval for smoother animation.
- Updated to allow for scrolling up the page.
- v2.0 - August 14, 2013
- Converted to vanilla JavaScript.
- Removed dependency on jQuery.
- v1.1 - June 7, 2013
- Switched to MIT license.
- v1.1 - May 18, 2013
- Added jQuery noConflict mode.
- Updated tutorial.
- v1.0 - January 24, 2013
- Initial release.