scroll-into-view-if-needed

scroll-into-view-if-needed ·

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

const scrollIntoViewIfNeeded = require('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
scrollIntoViewIfNeeded(node)

// same behavior as Element.scrollIntoViewIfNeeded(true)
// see: https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoViewIfNeeded
scrollIntoViewIfNeeded(node, { centerIfNeeded: true })

// animate the transition by setting a duration (in milliseconds)
scrollIntoViewIfNeeded(node, { duration: 300 })

API

scrollIntoViewIfNeeded(target, [options])

New API introduced in v1.3.0

options

Type: Object

boundary

Type: Element
Default: document.documentElement

Outermost parent element that might be scrolled to bring target into view. Use this if you have multiple scrollable views and you need to limit what's scrolled. Also use this if you know that you will only need to scroll the parent of your target to skip performance costly checks.

centerIfNeeded

Type: boolean
Default: false

Center the target if possible, and if it's not already visible. If it's not centered but still visible it will not scroll.

duration

Type: number

Set a duration in milliseconds to animate the transition between scroll positions on the x and/or y axis.

easing

Type: 'ease' | 'easeIn' | 'easeOut' | 'easeInOut' | 'linear'

Change the easing mechanism. This option takes effect when duration is set. In v2.0.0 it'll be possible to set your own bezier easing similar to CSS cubic-bezier().

offset

Type: Object

Used for creating whitespace between the target and the scroll container. Useful in scenarios where a position: fixed element might overlay the scroll container to "offset" the target.

However this option has known bugs and may be dropped or replaced in v2.0.0. If possible wrap your target in an element and create spacing using CSS padding or similar. This way you won't be affected by breaking changes here or the current bugs.

top

Type: number
Default: 0

Behaves similarily to margin-top. A negative value will "pull" the target upward, while a positive value will "push" it downwards.

right

Type: number
Default: 0

bottom

Type: number
Default: 0

left

Type: number
Default: 0

scrollIntoViewIfNeeded(target, [centerIfNeeded], [animateOptions], [finalElement], [offsetOptions])

Legacy API, will be deprecated in v2.0.0

centerIfNeeded

Type: boolean
Default: false

Legacy alias for options.centerIfNeeded

animateOptions

Type: Object

duration

Type: number

Legacy alias for options.duration

easing

Type: string

Legacy alias for options.easing

finalElement

Type: string

Legacy alias for options.boundary

offsetOptions

Type: Object

offsetTop

Type: number

Legacy alias for options.offset.top

offsetRight

Type: number

Legacy alias for options.offset.right

offsetBottom

Type: number

Legacy alias for options.offset.bottom

offsetLeft

Type: number

Legacy alias for options.offset.left

Examples

React

import scrollIntoViewIfNeeded from 'scroll-into-view-if-needed'
import { Component } from 'react'

export default class Homepage extends Component {
  render() {
    return (
      <div>
        ...
        <a
          onClick={event => {
            scrollIntoViewIfNeeded(this._signupNode, {
              duration: 150,
            })
          }}
        >
          Signup Now!
        </a>
        ...
        <form
          ref={node => {
            this._signupNode = node
          }}
        >
          ...
        </form>
        ...
      </div>
    )
  }
}

1989 JS

<script src="https://unpkg.com/scroll-into-view-if-needed@latest"></script>
<script>
  var node = document.getElementById('hero')
  // if you don't have a bundler don't worry, you can access the global like the good old days
  scrollIntoViewIfNeeded(node)
</script>

Similar packages

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.