{"id":15105194,"url":"https://github.com/markcellus/scroll-js","last_synced_at":"2025-09-27T03:30:37.867Z","repository":{"id":26521467,"uuid":"29974395","full_name":"markcellus/scroll-js","owner":"markcellus","description":"Light cross-browser scroller that uses native javascript","archived":true,"fork":false,"pushed_at":"2023-02-11T16:34:28.000Z","size":5995,"stargazers_count":230,"open_issues_count":17,"forks_count":35,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-01-26T03:43:49.222Z","etag":null,"topics":["animation","cross-browser","ember","es6","javascript","polymer","react","scroll","scroller","scrolling","scrollto"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markcellus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2015-01-28T15:37:43.000Z","updated_at":"2024-01-26T03:43:49.223Z","dependencies_parsed_at":"2023-07-13T15:50:49.424Z","dependency_job_id":null,"html_url":"https://github.com/markcellus/scroll-js","commit_stats":{"total_commits":691,"total_committers":16,"mean_commits":43.1875,"dds":0.7424023154848046,"last_synced_commit":"0dc0acf27fefee900b0f5950ea6a56d4cb97812a"},"previous_names":["mkay581/scroll-js"],"tags_count":88,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markcellus%2Fscroll-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markcellus%2Fscroll-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markcellus%2Fscroll-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markcellus%2Fscroll-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markcellus","download_url":"https://codeload.github.com/markcellus/scroll-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234376917,"owners_count":18822416,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["animation","cross-browser","ember","es6","javascript","polymer","react","scroll","scroller","scrolling","scrollto"],"created_at":"2024-09-25T20:21:47.167Z","updated_at":"2025-09-27T03:30:32.468Z","avatar_url":"https://github.com/markcellus.png","language":"TypeScript","readme":"![build](https://img.shields.io/travis/markcellus/scroll-js)\n![npm](https://img.shields.io/npm/v/scroll-js)\n![node](https://img.shields.io/node/v/scroll-js)\n![minified](https://img.shields.io/bundlephobia/min/scroll-js)\n![downloads](https://img.shields.io/npm/dm/scroll-js)\n![license](https://img.shields.io/npm/l/scroll-js)\n\n## _This repository has been deprecated in favor of the [`scrollIntoView`](https://w3c.github.io/csswg-drafts/cssom-view/#dom-element-scrollintoview), which is supported in all major browsers. Please use that for scroll animations going forward. Thanks to all who have helped contribute to this package._\n\n# Scroll\n\nA light-weight library that will allow you to scroll any html element using native javascript.\nIn addition to providing extra scrolling features, this library also aims to be a polyfill for the [scrollTo](https://developer.mozilla.org/en-US/docs/Web/API/Window/scroll)\nand [scrollIntoView](https://drafts.csswg.org/cssom-view/#dom-element-scrollintoview) APIs and allows you to scroll\nusing animations that are based loosely on the\n[`scrollOptions` of the DOM specification](https://drafts.csswg.org/cssom-view/#dictdef-scrolloptions).\nManipulates native scroll properties so that native events fire appropriately and uses browser's animation frames for\nfast and smooth rendering.\n\n## Why use this over other scroll libraries and plugins?\n\nMany other scroller libraries use absolutely positioning, css animations, transitions and other types of workarounds directly on\nthe `window.document`, `\u003chtml\u003e`, `\u003cbody\u003e` and other elements to \"fake\" a scrolling effect in order to get the scroller to behave.\n\nWhile this is clever, desktop and mobile devices (mobile mainly), heavily depend on the natural scroll events of these\nelements to do helpful things for the user.\nLike hiding the location url bar as you scroll down the window of the document (on mobile browsers), for instance. Or\n[pausing heavy processes](http://developer.telerik.com/featured/scroll-event-change-ios-8-big-deal/), until\nthe user is done performing a task as to not interrupt them, or adding inertia or natural momentum when scrolling. So\nit's increasingly important that the scroll logic added to these elements is done in a way that\nlends nicely to these use cases, which is what this library does.\n\n## Benefits\n\n-   pure, native javascript\n-   returns [Promises](https://www.ecma-international.org/ecma-262/6.0/#sec-promise-objects) so you can do things when scrolling completes (`async`/`await` is supported)\n-   no css transitions, animations or absolute positioning hacks\n-   manually scroll to any portion of a page and detect when done\n-   safe to use on the `document.body` element\n-   supports scroll options from CSS DOM specification\n-   battery-friendly -- uses minimal amount of CPU power (no processing on inactive tabs, and hidden elements!)\n-   fast and smooth rendering (no choppiness)\n-   does not hijack native browser functionality (i.e. inertia scrolling, momentum defaults)\n-   native \"onscroll\" events can still be used ([window.onscroll](https://developer.mozilla.org/en-US/docs/Web/API/window.onscroll) and\n    [Element.onscroll](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers.onscroll))\n-   Both non-AMD and AMD compatible\n\n## Installation\n\nYou can install the library as a npm module by running the following command:\n\n```\nnpm i scroll-js\n```\n\n## Importing\n\nAfter installing, you can either `import` the component into your file:\n\n```js\nimport { scrollTo, scrollIntoView } from 'scroll-js';\n```\n\nOr, you can reference any of the files made available in the dist folder in your html file.\n\n```html\n\u003cscript src=\"node_modules/scroll-js/dist/scroll.js\"\u003e\u003c/script\u003e\n```\n\n## Usage\n\nIn addition to the samples below, you can find more in the [examples](/examples) folder.\n\n### Scrolling the window\n\n```js\nimport { scrollTo } from 'scroll-js';\n\nscrollTo(window, { top: 500 }).then(function () {\n    // window has scrolled 500 pixels down the page\n});\n```\n\n### Scrolling an element\n\nYou can manually scroll any element on a page and optionally detect when done. Just make sure the element you want to scroll has:\n\n1. A specified `height` css property.\n1. css `overflow` property that is set to `hidden`.\n1. Content that extends beyond the specified height.\n\nThe following example scrolls the window (document body).\n\n```javascript\nimport { scrollTo } from 'scroll-js';\nscrollTo(document.body, { top: 500 }).then(function () {\n    //scrolling down 500 pixels has completed!\n});\n```\n\n### Scroll to an element\n\n```javascript\nimport { scrollIntoView } from 'scroll-js';\nvar myElement = document.body.getElementsByClassName('my-element')[0];\nscrollIntoView(myElement, document.body, { behavior: 'smooth' }).then(\n    function () {\n        // done scrolling document's body to show myElement\n    }\n);\n```\n\n### Scroll easing\n\nYou can scroll with easing using the [`behavior` option of the scrollTo specification](https://drafts.csswg.org/cssom-view/#enumdef-scrollbehavior).\n\n```javascript\nimport { scrollTo } from 'scroll-js';\nscrollTo(document.body, { top: 600, behavior: 'smooth' }).then(function () {\n    // scrolled down 600 pixels smoothly\n});\n```\n\nEasing is also supported simply by passing the `easing` option with an easing string that can be found in the\n[src/scroll.ts file](/src/scroll.ts#L1).\n\n```javascript\nimport { scrollTo } from 'scroll-js';\nscrollTo(document.body, { top: 200, easing: 'ease-in-out' }).then(function () {\n    // scrolled down 200 pixels, easing on beginning and end\n});\n```\n\nNote that even though `easing` option is supported by this package,\nit is not guaranteed that it will be supported by the specification.\n\n### Detect scroll events\n\nListen in on native scroll events the same way you would if a user was scrolling with a mouse or touch event.\n\n```javascript\nimport { scrollTo } from 'scroll-js';\nwindow.addEventListener('scroll', function () {\n    // scrolling!\n});\nscrollTo(document.body, { top: 300 }); // scroll to trigger event\n```\n\n## API Documentation\n\n### scrollTo(element, options)\n\n| Option    | Type              | Description                                                                                      |\n| --------- | ----------------- | ------------------------------------------------------------------------------------------------ |\n| `element` | `HTMLElement`     | The element to scroll                                                                            |\n| `options` | `ScrollToOptions` | A set of scroll options (see writeup below) (i.e. `{behavior: 'smooth', top: '20', left: '0''}`) |\n\n#### scrollTo Options\n\nThe `scrollTo` method allows a set of options which are synonymous with the\n[ScrollToOptions](https://drafts.csswg.org/cssom-view/#dictdef-scrolltooptions) of the CSS specification,\nbut some additional ones are provided by this library until supported natively.\n\n| Option     | Type   | Description                                                                                                                                                                                                                                                                                              |\n| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `behavior` | String | The type of [scroll behavior](https://drafts.csswg.org/cssom-view/#enumdef-scrollbehavior) which can be set to `auto` or `smooth`. This is the recommended option since this is already natively supported. **If this is set, all other options are ignored**.                                           |\n| `duration` | Number | The number of milliseconds the scroll will take to complete                                                                                                                                                                                                                                              |\n| `easing`   | String | The easing to use when scrolling. Only keyword values of the [animation-timing-function](https://drafts.csswg.org/css-animations/#animation-timing-function) are supported. But passing function values will eventually be supported also (ie. `cubic-bezier(0.1, 0.7, 1.0, 0.1)`, `steps(4, end)`, etc) |\n\n### scrollIntoView(element, [scroller], [options])\n\n| Option     | Type                    | Description                                                                                                                      |\n| ---------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |\n| `element`  | `HTMLElement`           | The element to scroll into the viewport                                                                                          |\n| `scroller` | `HTMLElement`           | The element to be scrolled (defaults to `document.body`)                                                                         |\n| `options`  | `ScrollIntoViewOptions` | A set of scroll options to scroll the element into view (see writeup below) (i.e. `{behavior: 'smooth', top: '20', left: '0''}`) |\n\n#### scrollIntoView Options\n\nA set of [ScrollIntoViewOptions](https://drafts.csswg.org/cssom-view/#dictdef-scrollintoviewoptions) can be passed to the `scrollIntoView` method.\n\n| Option     | Type   | Description                                                                                                                                            |\n| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `behavior` | String | The type of [scroll behavior](https://drafts.csswg.org/cssom-view/#enumdef-scrollbehavior) which can be set to `auto` or `smooth`. Defaults to `auto`. |\n\n## Examples\n\nCode samples showing how to use this package can be found in the [examples](examples) folder. To run them, pull down this project\nand\n\n```bash\nnpm start\n```\n\nWhich will make the examples available at http://localhost:9383/examples/.\n\n## Development\n\nRun tests:\n\n```\nnpm install\nnpm test\n```\n\n### E2E Tests\n\nThe following runs E2E tests on the files in the examples folder.\n\n```\nnpm run test:e2e\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkcellus%2Fscroll-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkcellus%2Fscroll-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkcellus%2Fscroll-js/lists"}