{"id":19237154,"url":"https://github.com/epicweb-dev/restore-scroll","last_synced_at":"2025-05-15T17:08:17.395Z","repository":{"id":209720310,"uuid":"724808133","full_name":"epicweb-dev/restore-scroll","owner":"epicweb-dev","description":"🌀 Restore scroll position of elements on page navigation","archived":false,"fork":false,"pushed_at":"2024-10-16T04:02:14.000Z","size":25,"stargazers_count":256,"open_issues_count":6,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-31T23:37:24.364Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/epicweb-dev/restore-scroll","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/epicweb-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-28T20:47:37.000Z","updated_at":"2025-03-18T16:47:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"0ef599a1-fb66-4a54-b864-b8b192d2a295","html_url":"https://github.com/epicweb-dev/restore-scroll","commit_stats":null,"previous_names":["epicweb-dev/restore-scroll"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epicweb-dev%2Frestore-scroll","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epicweb-dev%2Frestore-scroll/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epicweb-dev%2Frestore-scroll/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epicweb-dev%2Frestore-scroll/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/epicweb-dev","download_url":"https://codeload.github.com/epicweb-dev/restore-scroll/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247755554,"owners_count":20990620,"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":[],"created_at":"2024-11-09T16:25:03.085Z","updated_at":"2025-04-08T00:34:41.774Z","avatar_url":"https://github.com/epicweb-dev.png","language":"TypeScript","readme":"\u003cdiv\u003e\n  \u003ch1 align=\"center\"\u003e\u003ca href=\"https://npm.im/@epic-web/restore-scroll\"\u003e🌀 @epic-web/restore-scroll\u003c/a\u003e\u003c/h1\u003e\n  \u003cstrong\u003e\n    Restore scroll position of elements on page navigation\n  \u003c/strong\u003e\n  \u003cp\u003e\n    The \u003ccode\u003e\u0026lt;body\u0026gt;\u003c/code\u003e isn't the only thing that scrolls. When the user scrolls a list, then navigates back and forth, you may want to keep their scroll position where it was when they left. This library makes that easy.\n  \u003c/p\u003e\n\u003c/div\u003e\n\n```\nnpm install @epic-web/restore-scroll\n```\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca\n    alt=\"Epic Web logo\"\n    href=\"https://www.epicweb.dev\"\n  \u003e\n    \u003cimg\n      width=\"300px\"\n      src=\"https://github-production-user-asset-6210df.s3.amazonaws.com/1500684/257881576-fd66040b-679f-4f25-b0d0-ab886a14909a.png\"\n    /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n\u003chr /\u003e\n\n\u003c!-- prettier-ignore-start --\u003e\n[![Build Status][build-badge]][build]\n[![MIT License][license-badge]][license]\n[![Code of Conduct][coc-badge]][coc]\n\u003c!-- prettier-ignore-end --\u003e\n\n## The Problem\n\nWhen a user navigates to a new page, the browser will scroll the page to the\nposition it was at when the user left the page. This is a great feature, but\nit's not perfect. The browser only scrolls the `\u003cbody\u003e` element. If the user\nscrolls a list, then navigates back and forth, the browser will scroll the page\nto the top, but the list will still be scrolled to the position it was at when\nthe user left the page.\n\n## The Solution\n\nThis library provides a way to restore the scroll position of any element on the\npage you choose. It does this by storing the scroll position of the element in\nsession storage and then restoring it when the user navigates back to the page\n(very similar to how Remix handles scroll restoration for the `\u003cbody\u003e`).\n\nThis depends on React Router's `useNavigation` and `useLocation` hooks. It could\nprobably be generalized to work with other routers. PRs welcome.\n\n## Demo\n\n[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/edit/remix-run-remix-fczany?file=app%2Froutes%2F_index.tsx)\n\nNote: this demo is based on Remix, but will work with React Router as well.\n\n## Usage\n\n```tsx\nimport { ElementScrollRestoration } from '@epic-web/restore-scroll'\n\nreturn (\n\t\u003cdiv\u003e\n\t\t\u003cul id=\"christmas-gifts\"\u003e\n\t\t\t\u003cli\u003e🎁\u003c/li\u003e\n\t\t\t\u003cli\u003e🎂\u003c/li\u003e\n\t\t\t\u003cli\u003e🎉\u003c/li\u003e\n\t\t\t{/* ... */}\n\t\t\u003c/ul\u003e\n\t\t\u003cElementScrollRestoration elementQuery=\"#christmas-gifts\" /\u003e\n\t\u003c/div\u003e\n)\n```\n\nAnd that's it! Now when the user navigates away from the page and then back to\nit, the list will be scrolled to the position it was at when the user left the\npage.\n\nYou can also specify horizontal scroll for elements like carousels:\n\n```tsx\n\u003cElementScrollRestoration elementQuery=\"#christmas-gifts\" direction=\"horizontal\" /\u003e\n```\n## Tips:\n\n1. This requires an inline script, so you'll need to pass a `nonce` if you're\n   using a Content Security Policy that requires this.\n2. Make certain to place the `ElementScrollRestoration` component _after_ the\n   element you want to restore the scroll position of. This is because the\n   component will render a `\u003cscript\u003e` tag immediately after the element, and\n   that script will run immediately, so the element needs to be in the DOM\n   before the script runs.\n3. If you're computing the `id` and that value can change between navigations,\n   you may need to specify a `key` on `ElementScrollRestoration` to trigger the\n   inline script to be evaluated again and set the scroll position correctly.\n4. You'll want one of these components for each scrollable element you want to\n   restore the scroll position for.\n\n## License\n\nMIT\n\n\u003c!-- prettier-ignore-start --\u003e\n[build-badge]: https://img.shields.io/github/actions/workflow/status/epicweb-dev/restore-scroll/release.yml?branch=main\u0026logo=github\u0026style=flat-square\n[build]: https://github.com/epicweb-dev/restore-scroll/actions?query=workflow%3Arelease\n[license-badge]: https://img.shields.io/badge/license-MIT%20License-blue.svg?style=flat-square\n[license]: https://github.com/epicweb-dev/restore-scroll/blob/main/LICENSE\n[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square\n[coc]: https://kentcdodds.com/conduct\n\u003c!-- prettier-ignore-end --\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepicweb-dev%2Frestore-scroll","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fepicweb-dev%2Frestore-scroll","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepicweb-dev%2Frestore-scroll/lists"}