scroll-into-view-if-needed

What is scroll-into-view-if-needed?

The scroll-into-view-if-needed npm package is a smooth scroll polyfill for the 'scrollIntoViewIfNeeded' DOM method, which allows elements to be scrolled into the viewport if they are not already visible. It provides a way to scroll an element into view, aligning it according to the specified options only if it is not already in view.

What are scroll-into-view-if-needed's main functionalities?

Basic scrolling into view if needed

This is the simplest use case where you can call the method on an element to ensure it is visible in the viewport.

element.scrollIntoViewIfNeeded();

Custom options for scrolling

This allows you to define custom options for the scrolling behavior, such as the alignment of the scrolled-to element within the viewport.

scrollIntoViewIfNeeded(node, {block: 'nearest', inline: 'nearest'});

Polyfill for unsupported browsers

The package can be used as a polyfill to provide the functionality in browsers that do not support 'scrollIntoViewIfNeeded' natively.

import scrollIntoViewIfNeeded from 'scroll-into-view-if-needed';
scrollIntoViewIfNeeded(node);

Other packages similar to scroll-into-view-if-needed

smoothscroll-polyfill

This package is a polyfill for the smooth scroll behavior in the scrollTo, scrollBy, and scrollIntoView methods. It is similar to scroll-into-view-if-needed but focuses on polyfilling the smooth scroll behavior across all scrolling methods.

scroll-into-view

Similar to scroll-into-view-if-needed, this package provides a function to scroll an element into view. However, it does not specifically check if the element is already in view and always performs the scroll action.

zenscroll

Zenscroll is a vanilla JavaScript library that enables smooth animated scrolling to elements on the page. While it provides similar smooth scrolling functionality, it does not have the conditional 'if-needed' aspect of scroll-into-view-if-needed.

README

This is a ponyfill with the added ability of animating the scroll itself.

Demo

Kudos to @hsablonniere for sharing the original polyfill and @jocki84 for improving it!

Install

yarn add scroll-into-view-if-needed

Usage

import scrollIntoView from 'scroll-into-view-if-needed'
const node = document.getElementById('hero')

// similar behavior as Element.scrollIntoView({block: "nearest", inline: "nearest"})
// only that it is a no-op if `node` is already visible
// see: https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView
// same behavior as Element.scrollIntoViewIfNeeded()
// see: https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoViewIfNeeded
scrollIntoView(node, {
  scrollMode: 'if-needed',
  block: 'nearest',
  inline: 'nearest',
})

// same behavior as Element.scrollIntoViewIfNeeded(true) without the "IfNeeded" behavior
// see: https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoViewIfNeeded
scrollIntoView(node, { block: 'center', inline: 'center' })
// scrollMode is "always" by default

// smooth scroll if the browser supports it and if the element isn't visible
scrollIntoView(node, { behavior: 'smooth', scrollMode: 'if-needed' })

Ponyfill smooth scrolling

If you're ok with a larger bundlesize, you can use the ponyfill version so all your users experience smooth scrolling.

import scrollIntoView from 'scroll-into-view-if-needed/ponyfill'
const node = document.getElementById('hero')

// If all you want is for all your users to have stuff smooth scroll into view
scrollIntoView(node, { behavior: 'smooth' })

// combine it with any of the other options
scrollIntoView(node, {
  behavior: 'smooth',
  scrollMode: 'if-needed',
  block: 'nearest',
  inline: 'nearest',
})

// It returns a promise that is resolved when the animation is finished
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' })
}

Custom scrolling transition

If the default smooth scrolling ponyfill isn't the duration or easing you want, you can provide your own scrolling logic by giving behavior a callback.

import scrollIntoView from 'scroll-into-view-if-needed'
const node = document.getElementById('hero')

scrollIntoView(node, {
  // Your scroll actions will always be an array, even if there is nothing to scroll
  behavior: scrollActions =>
    // list is sorted from innermost (closest parent to your target) to outermost (often the document.body or viewport)
    scrollActions.forEach(([el, scrollTop, scrollLeft]) => {
      // implement the scroll anyway you want
      el.scrollTop = scrollTop
      el.scrollLeft = scrollLeft

      // If you need the relative scroll coordinates, for things like window.scrollBy style logic, just do the math
      const offsetTop = el.scrollTop - scrollTop
      const offsetLeft = el.scrollLeft - scrollLeft
    }),
  // all the other options (scrollMode, block, inline) still work, so you don't need to reimplement them (unless you really really want to)
})

More documentation will be added (hang in there)