scroll-into-view-if-needed

v3.1.0

Ponyfill for upcoming Element.scrollIntoView() APIs like scrollMode: if-needed, behavior: smooth and block: center For more information about how to use this package see README

Latest version published 1 year ago

License: MIT

NPM

GitHub

Package Health Score

73 / 100

security
No known security issues
popularity
Influential project
maintenance
Inactive
community
Sustainable

Explore Similar Packages

Security

No known security issues

All security vulnerabilities belong to production dependencies of direct and indirect packages.

Security and license risk for significant versions

All Versions

Version				Vulnerabilities	License Risk
3.1.0	\|	09/2023	Popular	0 C 0 H 0 M 0 L	0 H 0 M 0 L
3.0.10	\|	04/2023		0 C 0 H 0 M 0 L	0 H 0 M 0 L
2.2.31	\|	11/2022		0 C 0 H 0 M 0 L	0 H 0 M 0 L
1.5.1	\|	04/2018		0 C 0 H 0 M 0 L	0 H 0 M 0 L
1.4.1	\|	11/2017		0 C 0 H 0 M 0 L	0 H 0 M 0 L

License

MIT

Security Policy

Is your project affected by vulnerabilities?

Scan your projects for vulnerabilities. Fix quickly with automated fixes. Get started with Snyk for free.

Get started free

Popularity

Influential project

Weekly Downloads (2,656,756)

GitHub Stars: 1.39K
Forks: 76
Contributors: 30

Direct Usage Popularity

The npm package scroll-into-view-if-needed receives a total of 2,656,756 downloads a week. As such, we scored scroll-into-view-if-needed popularity level to be Influential project.

Based on project statistics from the GitHub repository for the npm package scroll-into-view-if-needed, we found that it has been starred 1,386 times.

Downloads are calculated as moving averages for a period of the last 12 months, excluding weekends and known missing data points.

Community

Sustainable

Readme.md: Yes
Contributing.md: No
Code of Conduct: Yes
Contributors: 30
Funding: No

With more than 10 contributors for the scroll-into-view-if-needed repository, this is possibly a sign for a growing and inviting community.

Embed Package Health Score Badge

Maintenance

Inactive

Commit Frequency

Open Issues: 20
Open PR: 2
Last Release: 1 year ago
Last Commit: 10 months ago

Further analysis of the maintenance status of scroll-into-view-if-needed based on released npm versions cadence, the repository activity, and other data points determined that its maintenance is Inactive.

An important project maintenance signal to consider for scroll-into-view-if-needed is that it hasn't seen any new versions released to npm in the past 12 months, and could be considered as a discontinued project, or that which receives low attention from its maintainers.

As a healthy sign for on-going project maintenance, we found that the GitHub repository had at least 1 pull request or issue interacted with by the community.

Keep your project healthy

Check your package.json

Ensure all the packages you're using are healthy and well-maintained

Snyk Vulnerability Scanner

Get health score & security insights directly in your IDE

Package

Node.js Compatibility: not defined

Age: 9 years
Dependencies: 1 Direct
Versions: 86
Install Size: 44.8 kB
Dist-tags: 1
# of Files: 10
Maintainers: 1
TS Typings: Yes

scroll-into-view-if-needed has more than a single and default latest tag published for the npm package. This means, there may be other tags available for this package, such as next to indicate future releases, or stable to indicate stable releases.

Not sure how to use scroll-into-view-if-needed?

To help you get started, we've collected the most common ways that scroll-into-view-if-needed is being used within popular public projects.

TheThingsNetwork / lorawan-stack / pkg / webui / components / form / index.js View on Github

componentDidUpdate(prevProps) {
    const { formError, isSubmitting, isValid } = this.props
    const { isSubmitting: prevIsSubmitting, formError: prevFormError } = prevProps

    // Scroll form notification into view if needed
    if (formError && !prevFormError) {
      scrollIntoView(this.notificationRef.current, { behavior: 'smooth' })
      this.notificationRef.current.focus({ preventScroll: true })
    }

    // Scroll invalid fields into view if needed and focus them
    if (prevIsSubmitting && !isSubmitting && !isValid) {
      const firstErrorNode = document.querySelectorAll('[data-needs-focus="true"]')[0]
      if (firstErrorNode) {
        scrollIntoView(firstErrorNode, { behavior: 'smooth' })
        firstErrorNode.querySelector('input,textarea').focus({ preventScroll: true })
      }
    }
  }

View more ways to use scroll-into-view-if-needed

scroll-into-view-if-needed

This used to be a ponyfill for Element.scrollIntoViewIfNeeded. Since then the CSS working group have decided to implement its features in Element.scrollIntoView as the option scrollMode: "if-needed". Thus this library got rewritten to implement that spec instead of the soon to be deprecated one.

Demo

Install

npm i scroll-into-view-if-needed

You can also use it from a CDN:

const { default: scrollIntoView } = await import(
  'https://esm.sh/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

What does ponyfilling smooth scrolling mean, and why is it implemented in smooth-scroll-into-view-if-needed instead? The answer is bundlesize. If this package adds smooth scrolling to browsers that's missing it then the overall bundlesize increases regardless of wether you use this feature or not.

Put it this way:

import scrollIntoView from 'scroll-into-view-if-needed'
// Even if all you do is this
scrollIntoView(node, { scrollMode: 'if-needed' })
// You would end up with the same bundlesize as people who need
// smooth scrolling to work in browsers that don't support it natively
scrollIntoView(node, { behavior: 'smooth', scrollMode: 'if-needed' })

That's why only native smooth scrolling is supported out of the box. There are two common ways you can smooth scroll browsers that don't support it natively. Below is all three, which one is best for you depends on what is the most important to your use case:: load time, consistency or quality.

Load time

In many scenarios smooth scrolling can be used as a progressive enhancement. If the user is on a browser that don't implement smooth scrolling it'll simply scroll instantly and your bundlesize is only as large as it has to be.

import scrollIntoView from 'scroll-into-view-if-needed'

scrollIntoView(node, { behavior: 'smooth' })

Consistency

If a consistent smooth scrolling experience is a priority and you really don't want any surprises between different browsers and enviroments. In other words don't want to be affected by how a vendor might implement native smooth scrolling, then smooth-scroll-into-view-if-needed is your best option. It ensures the same smooth scrolling experience for every browser.

import smoothScrollIntoView from 'smooth-scroll-into-view-if-needed'

smoothScrollIntoView(node, { behavior: 'smooth' })

Quality

If you want to use native smooth scrolling when it's available, and fallback to the smooth scrolling ponyfill:

import scrollIntoView from 'scroll-into-view-if-needed'
import smoothScrollIntoView from 'smooth-scroll-into-view-if-needed'

const scrollIntoViewSmoothly =
  'scrollBehavior' in document.documentElement.style
    ? scrollIntoView
    : smoothScrollIntoView

scrollIntoViewSmoothly(node, { behavior: 'smooth' })

API

scrollIntoView(target, [options])

> New API introduced in v1.3.0

options

Type: Object

behavior

Type: 'auto' | 'smooth' | Function
Default: 'auto'

> Introduced in v2.1.0

`'auto'`

The auto option unlocks a few interesting opportunities. The browser will decide based on user preferences wether it should smooth scroll or not. On top of that you can control/override scrolling behavior through the scroll-behavior CSS property.

Some people get motion sick from animations. You can use CSS to turn off smooth scrolling in those cases to avoid making them dizzy:

html,
.scroll-container {
  overflow: scroll;
}

html,
.scroll-container {
  scroll-behavior: smooth;
}
@media (prefers-reduced-motion) {
  html,
  .scroll-container {
    scroll-behavior: auto;
  }
}

`'smooth'`

Using behavior: 'smooth' is the easiest way to smooth scroll an element as it does not require any CSS, just a browser that implements it. More information.

`Function`

When given a function then this library will only calculate what should be scrolled and leave it up to you to perform the actual scrolling.

The callback is given an array over actions. Each action contain a reference to an element that should be scrolled, with its top and left scrolling coordinates. What you return is passed through, allowing you to implement a Promise interface if you want to (check smooth-scroll-into-view-if-needed to see an example of that).

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: (actions) =&gt;
    // list is sorted from innermost (closest parent to your target) to outermost (often the document.body or viewport)
    actions.forEach(({ el, top, left }) =&gt; {
      // implement the scroll anyway you want
      el.scrollTop = top
      el.scrollLeft = left

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

Check the demo to see an example with popmotion and a spring transition.

> If you only need the custom behavior you might be better off by using the compute library directly: https://github.com/scroll-into-view/compute-scroll-into-view

block

Type: 'start' | 'center' | 'end' | 'nearest'
Default: 'center'

> Introduced in v2.1.0

More info.

inline

Type: 'start' | 'center' | 'end' | 'nearest'
Default: 'nearest'

> Introduced in v2.1.0

More info.

scrollMode

Type: 'always' | 'if-needed'
Default: 'always'

> Introduced in v2.1.0

More info.

boundary

Type: Element | Function

> Function introduced in v2.1.0, Element introduced in v1.1.0

More info.

skipOverflowHiddenElements

Type: Boolean
Default: false

> Introduced in v2.2.0

More info.

TypeScript support

When the library itself is built on TypeScript there's no excuse for not publishing great library definitions!

This goes beyond just checking if you misspelled behavior: 'smoooth' to the return type of a custom behavior:

const scrolling = scrollIntoView(document.body, {
  behavior: actions =&gt; {
    return new Promise(
      ...
    )
  },
})
// TypeScript understands that scrolling is a Promise, you can safely await on it
scrolling.then(() =&gt; console.log('done scrolling'))

You can optionally use a generic to ensure that options.behavior is the expected type. It can be useful if the custom behavior is implemented in another module:

const customBehavior = actions =&gt; {
    return new Promise(
      ...
    )
  }

const scrolling = scrollIntoView&gt;(document.body, {
  behavior: customBehavior
})
// throws if customBehavior does not return a promise

The options are available for you if you are wrapping this libary in another abstraction (like a React component):

import scrollIntoView, { type Options } from 'scroll-into-view-if-needed'

interface CustomOptions extends Options {
  useBoundary?: boolean
}

function scrollToTarget(selector, options: Options = {}) {
  const { useBoundary = false, ...scrollOptions } = options
  return scrollIntoView(document.querySelector(selector), scrollOptions)
}

Breaking API changes from v1

Since v1 ponyfilled Element.scrollIntoViewIfNeeded, while v2 ponyfills Element.scrollIntoView, there are breaking changes from the differences in their APIs.

The biggest difference is that the new behavior follows the spec, so the "if-needed" behavior is not enabled by default:

v1

import scrollIntoViewIfNeeded from 'scroll-into-view-if-needed'

// Only scrolls into view if needed, and to the nearest edge
scrollIntoViewIfNeeded(target)

v2

import scrollIntoView from 'scroll-into-view-if-needed'

// Must provide these options to behave the same way as v1 default
scrollIntoView(target, { block: 'nearest', scrollMode: 'if-needed' })

centerIfNeeded

The old Element.scrollIntoView api only had two settings, align to top or bottom. Element.scrollIntoViewIfNeeded had two more, align to the center or nearest edge. The Element.scrollIntoView spec now supports these two modes as block: 'center' and block: 'nearest'. Breaking changes sucks, but on the plus side your code is now more portable and will make this library easier to delete from your codebase on the glorious day browser support is good enough.

v1

import scrollIntoViewIfNeeded from 'scroll-into-view-if-needed'

// v1.3.x and later
scrollIntoViewIfNeeded(target, { centerIfNeeded: true })
scrollIntoViewIfNeeded(target, { centerIfNeeded: false })
// v1.2.x and earlier
scrollIntoViewIfNeeded(target, true)
scrollIntoViewIfNeeded(target, false)

v2

import scrollIntoView from 'scroll-into-view-if-needed'

scrollIntoView(target, { block: 'center' })
scrollIntoView(target, { block: 'nearest' })

duration

More information.

v1

import scrollIntoViewIfNeeded from 'scroll-into-view-if-needed'

scrollIntoViewIfNeeded(target, { duration: 300 })

v2

import scrollIntoView from 'scroll-into-view-if-needed'
// or
import scrollIntoView from 'smooth-scroll-into-view-if-needed'

scrollIntoView(target, { behavior: 'smooth' })

easing

This feature is removed, but you can achieve the same thing by implementing behavior: Function.

handleScroll

This is replaced with behavior: Function with one key difference. Instead of firing once per element that should be scrolled, the new API only fire once and instead give you an array so you can much easier batch and scroll multiple elements at the same time. Or sync scrolling with another element if that's the kind of stuff you're into, I don't judge.

-import scrollIntoViewIfNeeded from 'scroll-into-view-if-needed'
+import scrollIntoView from 'scroll-into-view-if-needed'

-scrollIntoViewIfNeeded(node, {handleScroll: (el, {scrollTop, scrollLeft}) =&gt; {
-  el.scrollTop = scrollTop
-  el.scrollLeft = scrollLeft
-}})
+scrollIntoView(node, {behavior: actions.forEach(({el, top, left}) =&gt; {
+  el.scrollTop = top
+  el.scrollLeft = left
+})})

offset

This was always a buggy feature and warned against using in v1 as it might get dropped. It's much safer to use CSS wrapper elements for this kind of thing.