DEPRECATION NOTICE:

Smooth Scroll is, without a doubt, my most popular and widely used plugin.

But in the time since I created it, a CSS-only method for smooth scrolling has emerged, and now has fantastic browser support. It can do things this plugin can't (like scrolling to anchor links from another page), and addresses bugs and limitations in the plugin that I have never gotten around to fixing.

This plugin has run its course, and the browser now offers a better, more feature rich and resilient solution out-of-the-box.

Learn how to animate scrolling to anchor links with one line of CSS, and how to prevent anchor links from scrolling behind fixed or sticky headers.

Thanks for the years of support!

---

Smooth Scroll

A lightweight script to animate scrolling to anchor links. Smooth Scroll works great with Gumshoe.

View the Demo on CodePen →

Getting Started | Scroll Speed | Easing Options | API | What's new? | Known Issues | Browser Compatibility | License

Quick aside: you might not need this library. There's a native CSS way to handle smooth scrolling that might fit your needs.

<hr>

Want to learn how to write your own vanilla JS plugins? Check out my Vanilla JS Pocket Guides or join the Vanilla JS Academy and level-up as a web developer. 🚀

<hr>

Getting Started

Compiled and production-ready code can be found in the dist directory. The src directory contains development code.

1. Include Smooth Scroll on your site.

There are two versions of Smooth Scroll: the standalone version, and one that comes preloaded with polyfills for closest(), requestAnimationFrame(), and CustomEvent(), which are only supported in newer browsers.

If you're including your own polyfills or don't want to enable this feature for older browsers, use the standalone version. Otherwise, use the version with polyfills.

Direct Download

You can download the files directly from GitHub.

<script src="path/to/smooth-scroll.polyfills.min.js"></script>

CDN

You can also use the jsDelivr CDN. I recommend linking to a specific version number or version range to prevent major updates from breaking your site. Smooth Scroll uses semantic versioning.

<!-- Always get the latest version -->
<!-- Not recommended for production sites! -->
<script src="https://cdn.jsdelivr.net/gh/cferdinandi/smooth-scroll/dist/smooth-scroll.polyfills.min.js"></script>

<!-- Get minor updates and patch fixes within a major version -->
<script src="https://cdn.jsdelivr.net/gh/cferdinandi/smooth-scroll@15/dist/smooth-scroll.polyfills.min.js"></script>

<!-- Get patch fixes within a minor version -->
<script src="https://cdn.jsdelivr.net/gh/cferdinandi/smooth-scroll@15.0/dist/smooth-scroll.polyfills.min.js"></script>

<!-- Get a specific version -->
<script src="https://cdn.jsdelivr.net/gh/cferdinandi/smooth-scroll@15.0.0/dist/smooth-scroll.polyfills.min.js"></script>

NPM

You can also use NPM (or your favorite package manager).

npm install smooth-scroll

2. Add the markup to your HTML.

No special markup needed—just standard anchor links. Give the anchor location an ID just like you normally would.

<a data-scroll href="#bazinga">Anchor Link</a>
...
<div id="bazinga">Bazinga!</div>

Note: Smooth Scroll does not work with <a name="anchor"></a> style anchors. It requires IDs.

3. Initialize Smooth Scroll.

In the footer of your page, after the content, initialize Smooth Scroll by passing in a selector for the anchor links that should be animated. And that's it, you're done. Nice work!

<script>
	var scroll = new SmoothScroll('a[href*="#"]');
</script>

Note: The a[href*="#"] selector will apply Smooth Scroll to all anchor links. You can selectively target links using any other selector(s) you'd like. Smooth Scroll accepts multiple selectors as a comma separated list. Example: '.js-scroll, [data-scroll], #some-link'.

Scroll Speed

Smooth Scroll allows you to adjust the speed of your animations with the speed option.

This a number representing the amount of time in milliseconds that it should take to scroll 1000px. Scroll distances shorter than that will take less time, and scroll distances longer than that will take more time. The default is 300ms.

var scroll = new SmoothScroll('a[href*="#"]', {
	speed: 300
});

If you want all of your animations to take exactly the same amount of time (the value you set for speed), set the speedAsDuration option to true.

// All animations will take exactly 500ms
var scroll = new SmoothScroll('a[href*="#"]', {
	speed: 500,
	speedAsDuration: true
});

Easing Options

Smooth Scroll comes with about a dozen common easing patterns. Here's a demo of the different patterns.

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

You can also pass in your own custom easing pattern using the customEasing option.

var scroll = new SmoothScroll('a[href*="#"]', {
	// Function. Custom easing pattern
	// If this is set to anything other than null, will override the easing option above
	customEasing: function (time) {

		// return <your formulate with time as a multiplier>

		// Example: easeInOut Quad
		return time < 0.5 ? 2 * time * time : -1 + (4 - 2 * time) * time;

	}
});

API

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.

Options and Settings

You can pass options and callbacks into Smooth Scroll when instantiating.

var scroll = new SmoothScroll('a[href*="#"]', {

	// Selectors
	ignore: '[data-scroll-ignore]', // Selector for links to ignore (must be a valid CSS selector)
	header: null, // Selector for fixed headers (must be a valid CSS selector)
	topOnEmptyHash: true, // Scroll to the top of the page for links with href="#"

	// Speed & Duration
	speed: 500, // Integer. Amount of time in milliseconds it should take to scroll 1000px
	speedAsDuration: false, // If true, use speed as the total duration of the scroll animation
	durationMax: null, // Integer. The maximum amount of time the scroll animation should take
	durationMin: null, // Integer. The minimum amount of time the scroll animation should take
	clip: true, // If true, adjust scroll distance to prevent abrupt stops near the bottom of the page
	offset: function (anchor, toggle) {

		// Integer or Function returning an integer. How far to offset the scrolling anchor location in pixels
		// This example is a function, but you could do something as simple as `offset: 25`

		// An example returning different values based on whether the clicked link was in the header nav or not
		if (toggle.classList.closest('.my-header-nav')) {
			return 25;
		} else {
			return 50;
		}

	},

	// Easing
	easing: 'easeInOutCubic', // Easing pattern to use
	customEasing: function (time) {

		// Function. Custom easing pattern
		// If this is set to anything other than null, will override the easing option above

		// return <your formulate with time as a multiplier>

		// Example: easeInOut Quad
		return time < 0.5 ? 2 * time * time : -1 + (4 - 2 * time) * time;

	},

	// History
	updateURL: true, // Update the URL on scroll
	popstate: true, // Animate scrolling with the forward/backward browser buttons (requires updateURL to be true)

	// Custom Events
	emitEvents: true // Emit custom events

});

Custom Events

Smooth Scroll emits three custom events:

• scrollStart is emitted when the scrolling animation starts.
• scrollStop is emitted when the scrolling animation stops.
• scrollCancel is emitted if the scrolling animation is canceled.

All three events are emitted on the document element and bubble up. You can listen for them with the addEventListener() method. The event.detail object includes the anchor and toggle elements for the animation.

// Log scroll events
var logScrollEvent = function (event) {

	// The event type
	console.log('type:', event.type);

	// The anchor element being scrolled to
	console.log('anchor:', event.detail.anchor);

	// The anchor link that triggered the scroll
	console.log('toggle:', event.detail.toggle);

};

// Listen for scroll events
document.addEventListener('scrollStart', logScrollEvent, false);
document.addEventListener('scrollStop', logScrollEvent, false);
document.addEventListener('scrollCancel', logScrollEvent, false);

Methods

Smooth Scroll also exposes several public methods.

animateScroll()

Animate scrolling to an anchor.

var scroll = new SmoothScroll(