Repository files navigation

Lower level API that is used by theponyfillscroll-into-view-if-needed to compute where (if needed) elements should scroll based onoptions defined in the spec and thescrollMode: "if-needed" draft spec proposal.Use this if you want the smallest possible bundlesize and is ok with implementing the actual scrolling yourself.

Scrolling SVG elements are supported, as well as Shadow DOM elements. TheVisualViewport API is also supported, ensuring scrolling works properly on modern devices. Quirksmode is also supported as long as you polyfilldocument.scrollingElement.

• Install
• Usage
• API
  • compute(target, options)
  • options
    • block
    • inline
    • scrollMode
    • boundary
    • skipOverflowHiddenElements

npm i compute-scroll-into-view

You can also use it from a CDN:

const{ compute}=awaitimport('https://esm.sh/compute-scroll-into-view')

import{compute}from'compute-scroll-into-view'constnode=document.getElementById('hero')// same behavior as Element.scrollIntoView({block: "nearest", inline: "nearest"})// see: https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoViewconstactions=compute(node,{scrollMode:'if-needed',block:'nearest',inline:'nearest',})// same behavior as Element.scrollIntoViewIfNeeded(true)// see: https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoViewIfNeededconstactions=compute(node,{scrollMode:'if-needed',block:'center',inline:'center',})// Then perform the scrolling, use scroll-into-view-if-needed if you don't want to implement this partactions.forEach(({ el, top, left})=>{el.scrollTop=topel.scrollLeft=left})

Type:Object

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

Control the logical scroll position on the y-axis. The spec states that theblock direction is related to thewriting-mode, but this is not implemented yet in this library.This means thatblock: 'start' aligns to the top edge andblock: 'end' to the bottom.

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

Likeblock this is affected by thewriting-mode. In left-to-right pagesinline: 'start' will align to the left edge. In right-to-left it should be flipped. This will be supported in a future release.

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

This is a proposed addition to the spec that you can track here:w3c/csswg-drafts#5677

This library will be updated to reflect any changes to the spec and will provide a migration path.To be backwards compatible withElement.scrollIntoViewIfNeeded if something is not 100% visible it will count as "needs scrolling". If you need a different visibility ratio your best option would be to implement anIntersection Observer.

Type:Element | Function

By default there is no boundary. All the parent elements of your target is checked until it reaches the viewport (document.scrollingElement) when calculating layout and what to scroll.By passing a boundary you can short-circuit this loop depending on your needs:

• Prevent the browser window from scrolling.
• Scroll elements into view in a list, without scrolling container elements.

You can also pass a function to do more dynamic checks to override the scroll scoping:

constactions=compute(target,{boundary:(parent)=>{// By default `overflow: hidden` elements are allowed, only `overflow: visible | clip` is skipped as// this is required by the CSSOM specif(getComputedStyle(parent)['overflow']==='hidden'){returnfalse}returntrue},})

Type:Boolean
Default:false

By default thespec states thatoverflow: hidden elements should be scrollable because it hasbeen used to allow programatic scrolling. This behavior can sometimes lead toscrolling issues when you have a node that is a child of anoverflow: hidden node.

This package follows the conventionadopted by Firefox of setting a boolean option tonot scroll all nodes withoverflow: hidden set.