This is an addon to scroll-into-view-if-needed
that ponyfills smooth scrolling.
And while scroll-into-view-if-needed
use the same default options as browsers and the spec does, this library is a bit more opinionated and include bonus features that help you build great UIs.
Install
yarn add smooth-scroll-into-view-if-needed
Usage
import scrollIntoView from 'smooth-scroll-into-view-if-needed'
const node = document.getElementById('hero')
scrollIntoView(node)
scrollIntoView(node, {
scrollMode: 'if-needed',
block: 'nearest',
inline: 'nearest',
})
const sequence = async () => {
const slide = document.getElementById('slide-3')
await scrollIntoView(node, { behavior: 'smooth' })
return scrollIntoView(slide, { behavior: 'smooth' })
}
Polyfills
This library rely on Promise
and requestAnimationFrame
. This library does not ship with polyfills for these to keep bundlesizes as low as possible.
API
Check the full API in scroll-into-view-if-needed
.
This library differs from the API in scroll-into-view-if-needed
in the following ways:
- the second argument can't be a boolean, it must be either undefined or an object.
scrollIntoView(target, [options]) => Promise
scroll-into-view-if-needed
does not return anything, while this library will return a Promise that is resolved when all of the scrolling boxes are finished scrolling.
The ability to cancel animations will be added in a future version.
options
Type: Object
behavior
Type: 'auto' | 'smooth' | 'instant' | Function
Default: 'smooth'
This option deviates from scroll-into-view-if-needed
in two ways.
- The default value is
smooth
instead of auto
- Using
smooth
adds it to browsers that miss it, and overrides the native smooth scrolling in the browsers that have it to ensure the scrolling is consistent in any browser.
duration
Type: number
Default: 300
Introduced in v1.1.0
This setting is not a hard limit.
The duration of a scroll differs depending on how many elements is scrolled, and the capabilities of the browser.
On mobile the browser might pause or throttle the animation if the user switches to another tab.
And there might be nothing to scroll.
No matter the scenario a Promise is returned so you can await on it.
ease
Type: Function
Introduced in v1.1.0
The default easing is implemented like this, with t
being in the range of 0
=> 1
:
scrollIntoView(node, {
ease: t => 0.5 * (1 - Math.cos(Math.PI * t)),
})
Here's more examples, like easeInCubic etc: https://gist.github.com/gre/1650294#file-easing-js
Credits
- smoothscroll for the reference implementation of smooth scrolling.
More documentation will be added