{"bugs":{"url":"https://github.com/stipsan/scroll-into-view-if-needed/issues"},"dist":{"shasum":"1985e4ebd9735645b56741f26ff285a2817982f7","tarball":"https://registry.npmjs.org/scroll-into-view-if-needed/-/scroll-into-view-if-needed-2.1.3.tgz","fileCount":12,"integrity":"sha512-llhiCte16TqKM4acpSRCKDm7jtohrkOGwwyGVxL7rqAa1vZgawm7VfkAfXvFDXEKpUuMN1pQViT4iz9OIpL8HA==","signatures":[{"sig":"MEQCICz01IwgyCn0VUnmwHlCBtmPamKH+hskNSioYKRJS4iBAiAyDWylmUMXQHUEsIebcIGOP+5NKRBPcGFGX2nqiI/D9w==","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":63133,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJa6NzoCRA9TVsSAnZWagAAx7IQAKF44WxpEshmXfTqhQve\nav3lLUj29gVC0UqtrOwSPfkPSl/9iQY878b4U9wIW9XQNUtXsqTpNg3WytHB\nZ6wH+OuAsOmwX2TAEu40akMy49DUezi3JHF1Lzfp5z8HMvXidOFtYjmu8sGU\nvkThSRjWz4p+Zzw9cXQOFuUK9v3opwVOnzOHgNpBhM1pMzUJuSaD4K8c7SIW\nl4IUz8I/XfpGpQUktEBjmIOHJlv/cEbZOMD4NLsRfELToRGo/Qz+4v5RrcgX\ndinEtajAt1zFyWwQUgbUeB5u7ibjqZJjFht73bVEqMct/OKf48QSF3OBckzD\nrKvOq2/rn0XNBHFLLevKGTWySeXAtNDPe3RUJkchFKhNPf7hw318kTXXASVC\n7/iQ4VpsNSkseBG8QUc7jEYI4YlGb2dHSluEk87RWc2VXGrhq4rYoSSGaf6r\ne5AD5Ae7Y2F2yaxuSKOWKr6lcMg6ZBw+IJdaCAYtZZqAyS/vfcVQWZrHP+Fu\nnvqJhc11lGwb7VgML8grcDnQjvjiH1qoKS7qU45fMGtk9qHqfYX6et1rQYR9\nMrMYRkNcPGYuCRZx4wNQuJboos5zKUHNEyJWt0E4u/aOc5CNNx1BZhcMedXy\neMK6tIdqCSemPxxXleJZ6GxBkUm3YMUBlHC8bKBG+USvdPtEjmcqVO6tMLHc\nH1wb\r\n=n7Y3\r\n-----END PGP SIGNATURE-----\r\n"},"main":"index.js","name":"scroll-into-view-if-needed","files":["compute.js","es","typings","umd"],"author":{"name":"Stian Didriksen"},"module":"es/index.js","readme":"[](https://circleci.com/gh/stipsan/scroll-into-view-if-needed)\n[](https://npm-stat.com/charts.html?package=scroll-into-view-if-needed)\n[](https://www.npmjs.com/package/scroll-into-view-if-needed)\n[![gzip size][gzip-badge]][unpkg-dist]\n[![size][size-badge]][unpkg-dist]\n[![module formats: umd, cjs, and es][module-formats-badge]][unpkg-dist]\n[](https://github.com/semantic-release/semantic-release)\n\n\nThis used to be a [ponyfill](https://ponyfill.com) for\n`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.\n\n## [Demo](https://scroll-into-view-if-needed.netlify.com)\n\n## Install\n\n```bash\nyarn add scroll-into-view-if-needed\n```\n\n## Usage\n\n```js\n// es6 import\nimport scrollIntoView from 'scroll-into-view-if-needed'\n// or es5\nconst scrollIntoView = require('scroll-into-view-if-needed')\n\nconst node = document.getElementById('hero')\n\n// similar behavior as Element.scrollIntoView({block: \"nearest\", inline: \"nearest\"})\n// only that it is a no-op if `node` is already visible\n// see: https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView\n// same behavior as Element.scrollIntoViewIfNeeded()\n// see: https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoViewIfNeeded\nscrollIntoView(node, {\n scrollMode: 'if-needed',\n block: 'nearest',\n inline: 'nearest',\n})\n\n// same behavior as Element.scrollIntoViewIfNeeded(true) without the \"IfNeeded\" behavior\n// see: https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoViewIfNeeded\nscrollIntoView(node, { block: 'center', inline: 'center' })\n// scrollMode is \"always\" by default\n\n// smooth scroll if the browser supports it and if the element isn't visible\nscrollIntoView(node, { behavior: 'smooth', scrollMode: 'if-needed' })\n```\n\n### Ponyfill smooth scrolling\n\nWhat does ponyfilling smooth scrolling mean, and why is it implemented in [`smooth-scroll-into-view-if-needed`](https://github.com/stipsan/smooth-scroll-into-view-if-needed) instead?\nThe 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.\n\nPut it this way:\n\n```js\nimport scrollIntoView from 'scroll-into-view-if-needed'\n// Even if all you do is this\nscrollIntoIntoView(node, { scrollMode: 'if-needed' })\n// You end up with the same bundlesize as people who need\n// smooth scrolling to work in browsers that don't support it natively\nscrollIntoIntoView(node, { behavior: 'smooth', scrollMode: 'if-needed' })\n```\n\nBecause of this you need to choose a strategy that matches your priorities: load time, consistency or quality.\n\n##### Load time\n\nIn 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.\n\n```js\nimport scrollIntoView from 'scroll-into-view-if-needed'\n\nscrollIntoView(node, { behavior: 'smooth' })\n```\n\n##### Consistency\n\nIf 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`](https://github.com/stipsan/smooth-scroll-into-view-if-needed) is your best option. It ensures the same smooth scrolling experience for every browser.\n\n```js\nimport smoothScrollIntoView from 'smooth-scroll-into-view-if-needed'\n\nsmoothScrollIntoView(node, { behavior: 'smooth' })\n```\n\n##### Quality\n\nIf you want to use native smooth scrolling when it's available, and fallback to the smooth scrolling ponyfill:\n\n```js\nimport scrollIntoView from 'scroll-into-view-if-needed'\nimport smoothScrollIntoView from 'smooth-scroll-into-view-if-needed'\n\nconst scrollIntoViewSmoothly =\n 'scrollBehavior' in document.documentElement.style\n ? scrollIntoView\n : smoothScrollIntoView\n\nscrollIntoViewSmoothly(node, { behavior: 'smooth' })\n```\n\n## API\n\n### scrollIntoView(target, [options])\n\n> New API introduced in `v1.3.0`\n\n### options\n\nType: `Object`\n\n#### behavior\n\nType: `'auto' | 'smooth' | 'instant' | Function`
Default: `'auto'`\n\n> Introduced in `v2.1.0`\n\n##### `'auto'`\n\nThe auto option unlocks a few interesting opportunities.\nThe browser will decide based on user preferences wether it should smooth scroll or not.\nOn top of that you can control/override scrolling behavior through the [`scroll-behavior`](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-behavior) CSS property.\n\nSome people get [motion sick from animations](https://css-tricks.com/smooth-scrolling-accessibility/#article-header-id-5). You can use CSS to turn off smooth scrolling in those cases to avoid making them dizzy:\n\n```css\nhtml,\n.scroll-container {\n overflow: scroll;\n}\n\nhtml,\n.scroll-container {\n scroll-behavior: smooth;\n}\n@media (prefers-reduced-motion) {\n html,\n .scroll-container {\n scroll-behavior: auto;\n }\n}\n```\n\nQuick note, in the CSS property the `auto` keyword equals `behavior: 'instant'`, not `behavior: 'auto'` on `scrollIntoView`. **Yes**, this is confusing.\n\n##### `'smooth'`\n\nUsing `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.](#ponyfill-smooth-scrolling)\n\n##### `'instant'`\n\nThis is useful for scenarios where it's certain that smooth scrolling would make an interaction feel sluggish. Like keyboard navigation and other user experiences where the end user expect things to move _instantly_.\n\n##### `Function`\n\nWhen given a function then this library will only calculate what should be scrolled and leave it up to you to perform the actual scrolling.\n\nThe 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.\nWhat you return is passed through, allowing you to implement a Promise interface if you want to (check [`smooth-scroll-into-view-if-needed`](https://github.com/stipsan/smooth-scroll-into-view-if-needed) to see an example of that).\n\n```js\nimport scrollIntoView from 'scroll-into-view-if-needed'\nconst node = document.getElementById('hero')\n\nscrollIntoView(node, {\n // Your scroll actions will always be an array, even if there is nothing to scroll\n behavior: actions =>\n // list is sorted from innermost (closest parent to your target) to outermost (often the document.body or viewport)\n actions.forEach(({ el, top, left }) => {\n // implement the scroll anyway you want\n el.scrollTop = top\n el.scrollLeft = left\n\n // If you need the relative scroll coordinates, for things like window.scrollBy style logic or whatever, just do the math\n const offsetTop = el.scrollTop - top\n const offsetLeft = el.scrollLeft - left\n }),\n // all the other options (scrollMode, block, inline) still work, so you don't need to reimplement them (unless you really really want to)\n})\n```\n\nCheck the demo to see an [example with popmotion and a spring transition](https://scroll-into-view-if-needed.netlify.com/#override-behavior).\n\n#### block\n\nType: `'start' | 'center' | 'end' | 'nearest'`
Default: `'center'`\n\n> Introduced in `v2.1.0`\n\nControl the logical scroll position on the y-axis. The spec states that the `block` direction is related to the [writing-mode](https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode), but this is not implemented yet in this library.\nThis means that `block: 'start'` aligns to the top edge and `block: 'end'` to the bottom.\n\n#### inline\n\nType: `'start' | 'center' | 'end' | 'nearest'`
Default: `'nearest'`\n\n> Introduced in `v2.1.0`\n\nLike `block` this is affected by the [writing-mode](https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode). In left-to-right pages `inline: 'start'` will align to the left edge. In right-to-left it should be flipped. This will be supported in a future release.\n\n#### scrollMode\n\nType: `'always' | 'if-needed'`
Default: `'always'`\n\n> Introduced in `v2.1.0`\n\nThis is a proposed addition to the spec that you can track here: https://github.com/w3c/csswg-drafts/pull/1805\n\nThis library will be updated to reflect any changes to the spec and will provide a migration path.\nTo be backwards compatible with `Element.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 an [Intersection Observer](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).\n\n#### boundary\n\nType: `Element | Function`\n\n> `Function` introduced in `v2.1.0`, `Element` introduced in `v1.1.0`\n\nBy default there is no boundary. All the parent elements of your target is checked until it reaches the viewport (`document.documentElement`) when calculating layout and what to scroll.\nYou can use this option to do things like:\n\n* Prevent the browser window from scrolling.\n* Scroll things into view below the fold without scrolling to it.\n* Scroll elements into view in a list, without scrolling container elements.\n* Prematurely optimizing performance instead of code-splitting your app.\n\nYou can also pass a function to do more dynamic checks to override the scroll scoping:\n\n```js\nscrollIntoView(target, {\n boundary: parent => {\n // By default `overflow: hidden` elements are allowed, only `overflow: visible | clip` is skipped as\n // this is required by the CSSOM spec\n if (getComputedStyle(parent)['overflow'] === 'hidden') {\n return false\n }\n\n return true\n },\n})\n```\n\n# Breaking API changes from v1\n\nSince v1 ponyfilled Element.scrollIntoViewIfNeeded, while v2 ponyfills Element.scrollIntoView, there are breaking changes from the differences in their APIs.\n\nThe biggest difference is that the new behavior follows the spec, so the \"if-needed\" behavior is **not enabled by default:**\n\n##### v1\n\n```js\nimport scrollIntoViewIfNeeded from 'scroll-into-view-if-needed'\n\n// Only scrolls into view if needed, and to the nearest edge\nscrollIntoViewIfNeeded(target)\n```\n\n##### v2\n\n```js\nimport scrollIntoView from 'scroll-into-view-if-needed'\n\n// Must provide these options to behave the same way as v1 default\nscrollIntoView(target, { block: 'nearest', scrollMode: 'if-needed' })\n```\n\n#### centerIfNeeded\n\nThe old `Element.scrollIntoView` api only had two settings, align to top or bottom. [`Element.scrollIntoViewIfNeeded`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoViewIfNeeded) had two more, align to the center or nearest edge.\nThe `Element.scrollIntoView` spec now supports these two modes as `block: 'center'` and `block: 'nearest'`.\nBreaking 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.\n\n##### v1\n\n```js\nimport scrollIntoViewIfNeeded from 'scroll-into-view-if-needed'\n\n// v1.3.x and later\nscrollIntoViewIfNeeded(target, { centerIfNeeded: true })\nscrollIntoViewIfNeeded(target, { centerIfNeeded: false })\n// v1.2.x and earlier\nscrollIntoViewIfNeeded(target, true)\nscrollIntoViewIfNeeded(target, false)\n```\n\n##### v2\n\n```js\nimport scrollIntoView from 'scroll-into-view-if-needed'\n\nscrollIntoView(target, { block: 'center' })\nscrollIntoView(target, { block: 'nearest' })\n```\n\n#### duration\n\n[More information.](#ponyfill-smooth-scrolling)\n\n##### v1\n\n```js\nimport scrollIntoViewIfNeeded from 'scroll-into-view-if-needed'\n\nscrollIntoViewIfNeeded(target, { duration: 300 })\n```\n\n##### v2\n\n```js\nimport scrollIntoView from 'scroll-into-view-if-needed'\n// or\nimport scrollIntoView from 'smooth-scroll-into-view-if-needed'\n\nscrollIntoView(target, { behavior: 'smooth' })\n```\n\n#### easing\n\nThis feature is removed, but you can achieve the same thing by implementing [`behavior: Function`](#function).\n\n#### handleScroll\n\nThis is replaced with [`behavior: Function`](#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.\n\n```diff\n-import scrollIntoViewIfNeeded from 'scroll-into-view-if-needed'\n+import scrollIntoView from 'scroll-into-view-if-needed'\n\n-scrollIntoViewIfNeeded(node, {handleScroll: (el, {scrollTop, scrollLeft}) => {\n- el.scrollTop = scrollTop\n- el.scrollLeft = scrollLeft\n-}})\n+scrollIntoView(node, {behavior: actions.forEach(({el, top, left}) => {\n+ el.scrollTop = top\n+ el.scrollLeft = left\n+})})\n```\n\n#### offset\n\nThis was always a buggy feature and warned against using in v1 as it might get dropped.\nIt's much safer to use CSS wrapper elements for this kind of thing.\n\n### scrollIntoViewIfNeeded(target, [centerIfNeeded], [animateOptions], [finalElement], [offsetOptions])\n\nThis API signature were warned to be dropped in `v2.0.0`, and it was.\n\n# Related packages\n\n* [smooth-scroll-into-view-if-needed](http://npmjs.com/package/smooth-scroll-into-view-if-needed) – ponyfills smooth scrolling.\n* [react-scroll-into-view-if-needed](https://www.npmjs.com/package/react-scroll-into-view-if-needed) – A thin wrapper to scroll your component into view.\n* [Don't be shy, add yours!](https://github.com/stipsan/scroll-into-view-if-needed/edit/master/README.md)\n\n# Who's using this\n\n* [zeit.co/docs](https://github.com/zeit/docs) – Documentation of ZEIT Now and other services.\n* [Selenium IDE](https://github.com/SeleniumHQ/selenium-ide) – An integrated development environment for Selenium scripts.\n* [Box UI Elements](https://github.com/box/box-ui-elements) – Box UI Elements are pre-built UI components that allow developers to add elements of the main Box web application into their own applications.\n* [react-responsive-ui](https://github.com/catamphetamine/react-responsive-ui) – Responsive React UI components.\n* [Mineral UI](https://github.com/mineral-ui/mineral-ui) –\n A design system and React component library for the web that lets you quickly build high-quality, accessible apps.\n* [Covalent](https://github.com/Teradata/covalent) – Teradata UI Platform built on Angular Material.\n* [docs.expo.io](https://github.com/expo/expo-docs) – Documentation for Expo, its SDK, client and services.\n* [Add yourself to the list 😉](https://github.com/stipsan/scroll-into-view-if-needed/edit/master/README.md)\n\n[gzip-badge]: http://img.badgesize.io/https://unpkg.com/scroll-into-view-if-needed/umd-scroll-into-view-if-needed.min.js?compression=gzip&label=gzip%20size&style=flat-square\n[size-badge]: http://img.badgesize.io/https://unpkg.com/scroll-into-view-if-needed/umd-scroll-into-view-if-needed.min.js?label=size&style=flat-square\n[unpkg-dist]: https://unpkg.com/scroll-into-view-if-needed/umd/\n[module-formats-badge]: https://img.shields.io/badge/module%20formats-umd%2C%20cjs%2C%20es-green.svg?style=flat-square\n","gitHead":"3b95ed7aa2d8461d9c09b03246d361a72ecaeb57","license":"MIT","release":{"prepare":["@semantic-release/npm"]},"scripts":{"dev":"concurrently 'tsc --watch' 'yarn build:cjs --watch'","lint":"eslint ./integration-examples","build":"yarn build:d.ts && yarn build:cjs && yarn build:es && yarn build:umd && yarn build:umd.min","clean":"rimraf 'umd' 'es' 'typings'","build:es":"BABEL_ENV=es babel src -d es --extensions '.ts'","prebuild":"yarn clean","build:cjs":"BABEL_ENV=cjs babel src -d . --extensions '.ts'","build:umd":"BABEL_ENV=umd NODE_ENV=development rollup -c -f umd -o umd/scroll-into-view-if-needed.js","precommit":"lint-staged","typecheck":"tsc --noEmit","build:d.ts":"tsc --emitDeclarationOnly","build:umd.min":"BABEL_ENV=umd NODE_ENV=production rollup -c -f umd -o umd/scroll-into-view-if-needed.min.js","prepublishOnly":"unset npm_config_cafile && yarn build"},"typings":"typings/index.d.ts","_npmUser":{"name":"stipsan","email":"stipsan@gmail.com"},"homepage":"https://scroll-into-view-if-needed.netlify.com","keywords":["behavior-smooth","if-needed","polyfill","ponyfill","scroll","scroll-into-view","scrollIntoView","scrollIntoViewIfNeeded","scrollMode","smooth","smoothscroll","typescript"],"prettier":{"semi":false,"overrides":[{"files":".babelrc","options":{"parser":"json"}}],"singleQuote":true,"trailingComma":"es5"},"browserify":{"transform":["loose-envify"]},"bundlesize":[{"path":"./umd/scroll-into-view-if-needed.min.js","maxSize":"1.75 kB"},{"path":"./umd/scroll-into-view-if-needed.js","maxSize":"3 kB"}],"repository":{"url":"git+https://github.com/stipsan/scroll-into-view-if-needed.git","type":"git"},"_npmVersion":"5.6.0","description":"Ponyfill for upcoming Element.scrollIntoView() APIs like scrollMode: if-needed, behavior: smooth and block: center","directories":{},"lint-staged":{"*.js":["prettier --write","git add"],"*.md":["prettier --write","git add"],"*.css":["prettier --write","git add"],"*.json":["prettier --write","git add"],"*.{ts,tsx}":["prettier --write","git add"],"**/.babelrc":["prettier --write","git add"],"**/package.json":["prettier-package-json --write","git add"]},"maintainers":[{"name":"stipsan","email":"stipsan@gmail.com"}],"sideEffects":false,"_nodeVersion":"8.11.1","publishConfig":{"tag":"next"},"_hasShrinkwrap":false,"readmeFilename":"README.md","devDependencies":{"husky":"0.14.3","eslint":"4.19.1","rimraf":"2.6.2","rollup":"0.58.2","prettier":"1.12.1","@babel/cli":"7.0.0-beta.46","typescript":"2.8.3","@babel/core":"7.0.0-beta.46","lint-staged":"7.0.5","babel-eslint":"8.2.3","concurrently":"3.5.1","semantic-release":"15.2.0","@babel/preset-env":"7.0.0-beta.46","eslint-plugin-react":"7.7.0","rollup-plugin-babel":"4.0.0-beta.4","eslint-plugin-import":"2.11.0","rollup-plugin-uglify":"3.0.0","prettier-package-json":"1.6.0","rollup-plugin-replace":"2.0.0","eslint-config-prettier":"2.9.0","rollup-plugin-commonjs":"9.1.3","@babel/preset-typescript":"7.0.0-beta.46","rollup-plugin-node-resolve":"3.3.0","babel-plugin-dev-expression":"0.2.1","@babel/plugin-external-helpers":"7.0.0-beta.46","babel-plugin-add-module-exports":"0.2.1"},"_npmOperationalInternal":{"tmp":"tmp/scroll-into-view-if-needed_2.1.3_1525210344380_0.34860850752562955","host":"s3://npm-registry-packages"},"_id":"scroll-into-view-if-needed@2.1.3","version":"2.1.3"}