Repository files navigation

Support for older versions: If you need documentation for versions prior 3.0.0 visitthis page

Lightweight Vanilla JS Smooth Scroll animation library without dependencies.

Create beautiful scroll animations with ease. ScrollToSmooth comes with a powerful set of options to get the best out of your project.
Powered by window.requestAnimationFrame() API and highly customizable.

Notice: If you just need simple smooth scrolling fora tags you might not need this library. Check out the nativeCSS scroll behavior andCSS scroll margin top.

View the Demo on CodePen 🎉

Getting Started |Usage |API |Noteworthy features |Browser Compatibility

npm install scrolltosmooth

<!-- Latest version with all easings --><scriptsrc="https://cdn.jsdelivr.net/npm/scrolltosmooth/dist/scrolltosmooth.pkgd.min.js"></script><!-- Latest version with linear easing only --><scriptsrc="https://cdn.jsdelivr.net/npm/scrolltosmooth/dist/scrolltosmooth.min.js"></script>

Directlydownload the repository and include the production ready code from thedist folder in your project.

Include the script in your code:

<scriptsrc="path/to/scrolltosmooth.min.js"></script>

import{scrollToSmooth,easeOutCubic}from'scrolltosmooth';letsmoothScroll=newscrollToSmooth('a',{targetAttribute:'href',duration:400,durationRelative:false,durationMin:false,durationMax:false,easing:easeOutCubic,onScrollStart:(data)=>{// do something},onScrollUpdate:(data)=>{// do something},onScrollEnd:(data)=>{// do something},offset:null});smoothScroll.init();

Type:string|element
Default:document

Specify a container element that contains the targets of the current initialization.

Type:string
Default:'href'

The attribute to determine the target element. Must be a valid selector!
You may use other attributes thanhref like for exampledata-scrollto so that the browsersdefault behaviour for anchor links does not change.

<spandata-scrollto="#target">Scroll to Section 1<span><sectionid="target">  Target Section</section>

Type:string|element|number
Default:null

Specify an element or a number to calculate the final position of the scrolling animation with offset to top.
Example:'#fixed-header'

Notice: You can also pass a numeric value for the offset option.

Type:boolean
default:true

If your targetAttribute contains an empty hash (#) on a href attribute force scroll to top.

Type:number
Default:400

Scroll animation duration in milliseconds.

Type:boolean|number
Default:false

durationRelative can be used to adjust the scroll animation duration by the amount of pixels to scroll.
Iftrue scrollToSmooth will use the value ofduration to calculate the amount of time in milliseconds to scroll the page by1000px.
You can also use a number, for example2000 to calculate the duration by2000px.

Scroll distances that are below that number will take less time than defined induration, while distances above will take longer to animate.

Type:number
Default:null

durationMin represents the minimum amount of milliseconds to perform the animation when using a relative duration.

Type:number
Default:null

just likedurationMin,durationMax represents the maximum amount of milliseconds to perform the animation when using a relative duration.

Type:string|function
Default:null

ScrollToSmooth comes with 31 predefined easing patterns.
By default scrollToSmooth is bundled with thelinear easing type.

Linear easings output progress value is equal to the input progress value

• linear

Ease-In progress value gradually increases in speed

• easeInQuad
• easeInCubic
• easeInQuart
• easeInQuint
• easeInSine
• easeInExpo
• easeInCirc
• easeInElastic
• easeInBack
• easeInBounce

Ease-Out progress value gradually decreases in speed

• easeOutQuad
• easeOutCubic
• easeOutQuart
• easeOutQuint
• easeOutSine
• easeOutExpo
• easeOutCirc
• easeOutElastic
• easeOutBack
• easeOutBounce

Ease-In-Out progress value increases in speed and slows down back afterwards

• easeInOutQuad
• easeInOutCubic
• easeInOutQuart
• easeInOutQuint
• easeInOutSine
• easeInOutExpo
• easeInOutCirc
• easeInOutElastic
• easeInOutBack
• easeInOutBounce

Every easing bundled with ScrollToSmooth can be imported individually by

import{easingName}from'scrolltosmooth';newscrollToSmooth('a',{  ...easing:easingName,  ...});

You can import other easing functions and use it with ScrollToSmooth.
The only requirement is that the method must take only one parameter representing the absolute progress of the animation in the bounds of 0 (beginning of the animation) and 1 (end of animation).

Example:

import{cubic}from'js-easing-library';newscrollToSmooth('a',{  ...easing:cubic,  ...});

You can also write your own easing functions:

Example:

newscrollToSmooth('a',{  ...easing:(t)=>t*t,// easeInQuad  ...});

Type:function
Default:null

Callback function to be executed when the scrolling animation has started.

Type:function
Default:null

Callback function to be executed while the scrolling animation runs.

Type:function
Default:null

Callback function to be executed when the scrolling animation has finished.

After creating a new instance of scrollToSmooth

letsmoothScroll=newscrollToSmooth(document.querySelector('.scrollToSmooth-link'));

You can use the following public methods to interact with it:

init:

Initialize

smoothScroll.init();

scrollTo:

You can use thescrollTo method to animate the scrolling to a specific element on the page:

smoothScroll.scrollTo('.your-selector');// ORsmoothScroll.scrollTo(document.querySelector('.your-selector'));

scrollTo can be also used with a numeric value.

Example:

smoothScroll.scrollTo(50);

scrollBy

scrollBy can be used just likescrollTo to trigger a scroll animation.
The only difference is you don't need a target element. Instead you can scroll by a fixed amount of pixels that gets added to the current scrollY.

smoothScroll.scrollBy(150);

cancelScroll:

while the animation is running you can callcancelScroll whenever you want to stop it immediately

smoothScroll.cancelScroll();

update:

Update the settings after initialization.

smoothScroll.update({duration:1000,fixedHeader:'#my-header-element'});

destroy:

Destroy the current instance of scrollToSmooth. You can then reinitialize the instance with theinit method.

smoothScroll.destroy();

onScrollStart:

newscrollToSmooth('a',{  ...onScrollStart:(data)=>{},  ...});

data contains an object with values forstartPosition andendPosition

onScrollUpdate:

newscrollToSmooth('a',{  ...onScrollUpdate:(data)=>{},  ...});

data contains an object with values forstartPosition,currentPosition andendPosition

onScrollEnd:

newscrollToSmooth('a',{  ...onScrollEnd:(data)=>{},  ...});

data contains an object with values forstartPosition andendPosition

TODO: custom events section

ScrollToSmooth adds custom elements to the top and bottom of the page. These elements will simulate expanded boundaries of your document while the scroll animation is running.That means the animation wont stop on the bottom of your page when the easing function would normally exceed the documents height.

If your page has a fixed header scrollToSmooth can use this element and add an offset before each section.
This ensures that the final scroll position does not cover any elements that should normally be visible.

Usage:

<divid="fixed-header"><imgsrc="path/to/your/logo.svg"/></div>

newscrollToSmooth('a',{  ...offset:'#fixed-header',// oroffset:document.getElementById('fixed-header'),  ...});

You don't need real links to animate scrolling using ScrollToSmooth.
For example, if you want to usespan tags as animation triggers you could do it like:

<nav><spandata-scrollto="#section-1">Scroll to section 1</span><spandata-scrollto="#section-2">Scroll to section 2</span></nav><sectionid="section-1"></section><sectionid="section-2"></section>

newscrollToSmooth('[data-scrollto]');

You can also define custom scroll triggers for specific events.
For example if you want to scroll down the page for 100px when clicking the spacebar:

constscrolltosmooth=newscrollToSmooth('a');document.addEventListener('keyup',event=>{if(event.keyCode===32){scrolltosmooth.scrollBy(100);}})

ScrollToSmooth automatically handles focus management after scrolling to an element so that the normal keyboard navigation won't get interrupted.

15+ ✔	7+ ✔	10+ ✔	12+ ✔	15+ ✔	6+ ✔

Support for older browsers requires a polyfill forrequestAnimationFrame()

If this project is helpfull you might support me out with a cup of coffee 🤗