smooth-scroll-into-view-if-needed
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.32 • Public • Published

    CircleCI Status npm stat npm version gzip size size module formats: umd, cjs, and es semantic-release smooth-scroll-into-view-if-needed

    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.

    Demo

    Install

    yarn add smooth-scroll-into-view-if-needed

    The UMD build is also available on unpkg:

    <script src="https://unpkg.com/smooth-scroll-into-view-if-needed/umd/smooth-scroll-into-view-if-needed.min.js"></script>

    You can find the library on window.scrollIntoView.

    Usage

    import scrollIntoView from 'smooth-scroll-into-view-if-needed'
    const node = document.getElementById('hero')
    
    // `options.behavior` is set to `smooth` by default so you don't have to pass options like in `scroll-into-view-if-needed`
    scrollIntoView(node)
    
    // combine it with any of the other options from 'scroll-into-view-if-needed'
    scrollIntoView(node, {
      scrollMode: 'if-needed',
      block: 'nearest',
      inline: 'nearest',
    })
    
    // a promise is always returned to help reduce boilerplate
    const sequence = async () => {
      const slide = document.getElementById('slide-3')
      // First smooth scroll to hero
      await scrollIntoView(node, { behavior: 'smooth' })
      // Then we scroll to a slide in a slideshow
      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.

    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' | 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.

    The options auto or Function behaves exactly like in scroll-into-view-if-needed.

    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 easeOutQuint based on these algorithms: https://gist.github.com/gre/1650294#file-easing-js

    Linear example:

    scrollIntoView(node, {
      ease: t => t,
    })

    Acceleration until halfway, then deceleration:

    scrollIntoView(node, {
      ease: t =>
        t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1,
    })

    Sine easing in and out:

    scrollIntoView(node, {
      ease: t => (1 + Math.sin(Math.PI * t - Math.PI / 2)) / 2,
    })

    Credits

    • smoothscroll for the reference implementation of smooth scrolling.

    More documentation will be added

    Install

    npm i smooth-scroll-into-view-if-needed

    DownloadsWeekly Downloads

    30,747

    Version

    1.1.32

    License

    MIT

    Unpacked Size

    28.5 kB

    Total Files

    8

    Last publish

    Collaborators

    • stipsan