{"id":15790,"library":"react-router-hash-link","title":"React Router Hash Link","description":"React Router Hash Link provides essential hash fragment scrolling functionality for applications built with React Router v4/5/6. Addressing a long-standing limitation in native React Router's `` component, this library ensures that navigation to URLs containing hash fragments (e.g., `/path#section-id`) correctly scrolls the viewport to the corresponding HTML element. It is particularly robust as it supports scrolling to elements that might be rendered asynchronously, which is common in data-driven React applications. The current stable version is 2.4.3, with a release cadence that has seen several minor updates, indicating active maintenance. Key differentiators include the ability to specify `smooth` scrolling behavior, a flexible `scroll` prop for custom scrolling logic (e.g., with offsets), and an `elementId` prop offering an alternative to hash fragments. It requires React Router's `BrowserRouter` for proper operation and ships with both `` and `` components, mirroring `react-router-dom`'s `Link` and `NavLink`.","status":"active","version":"2.4.3","language":"javascript","source_language":"en","source_url":"https://github.com/rafgraph/react-router-hash-link","tags":["javascript","react","react-router","link","hash-link","scroll"],"install":[{"cmd":"npm install react-router-hash-link","lang":"bash","label":"npm"},{"cmd":"yarn add react-router-hash-link","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-router-hash-link","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React applications.","package":"react","optional":false},{"reason":"Peer dependency, providing core React Router functionality.","package":"react-router-dom","optional":false}],"imports":[{"note":"CommonJS `require` syntax is not directly supported; use ESM imports for modern React applications.","wrong":"const { HashLink } = require('react-router-hash-link');","symbol":"HashLink","correct":"import { HashLink } from 'react-router-hash-link';"},{"note":"Both `HashLink` and `NavHashLink` are named exports from the root package.","wrong":"import NavHashLink from 'react-router-hash-link/NavHashLink';","symbol":"NavHashLink","correct":"import { NavHashLink } from 'react-router-hash-link';"}],"quickstart":{"code":"import { BrowserRouter, Routes, Route } from 'react-router-dom';\nimport { HashLink } from 'react-router-hash-link';\nimport React from 'react';\nimport ReactDOM from 'react-dom/client';\n\nfunction App() {\n return (\n \n \n
\n

Welcome to the Top

\n
\n
\n

Section 1

\n

This is the first section. Notice the smooth scroll effect.

\n
\n
\n

Section 2

\n

This is the second section. This one scrolls instantly.

\n
\n \n );\n}\n\nconst root = ReactDOM.createRoot(document.getElementById('root'));\nroot.render();","lang":"javascript","description":"Demonstrates basic usage of `HashLink` within a `BrowserRouter` context, showing how to navigate to and scroll smoothly or instantly to specific sections identified by hash fragments, including scrolling to the top of the page."},"warnings":[{"fix":"Review the 'Custom Link' section in the documentation for v2.0.0+ to adapt your custom link implementations, particularly regarding ref forwarding.","message":"Version 2.0.0 introduced breaking changes related to `React.forwardRef` implementation and simplified the custom link API. Projects upgrading from v1.x to v2.x may need to update custom link components.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your application is wrapped within a `` component from `react-router-dom`.","message":"This library requires React Router's `BrowserRouter` to function correctly. It will not work as expected with `HashRouter` or other router types.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For broader browser compatibility, consider installing a browser polyfill for smooth scrolling, such as `iamdustan/smoothscroll`.","message":"The `smooth` prop for smooth scrolling relies on the native `Element.scrollIntoView({ behavior: 'smooth' })` method. This feature is not supported in all browsers (e.g., older IE versions).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use distinct hash fragment names (e.g., `#my-section`) for specific elements you wish to scroll to, reserving `#` or `#top` for top-of-page navigation.","message":"Hash fragments `#` or `#top` are special and trigger scrolling to the top of the current page, aligning with HTML spec behavior. Using these as IDs for specific elements will not work as intended for section scrolling.","severity":"gotcha","affected_versions":">=2.2.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure the target element has a matching `id` attribute. For asynchronously loaded content, consider increasing the `timeout` prop on `HashLink` if content takes longer to render.","cause":"The element corresponding to the hash fragment or `elementId` prop could not be found in the DOM within the default 10-second timeout, or it never existed.","error":"TypeError: Cannot read properties of undefined (reading 'scrollIntoView')"},{"fix":"Verify that your application uses `BrowserRouter` and that the `id` attribute of your target element precisely matches the hash fragment (e.g., `` targets `
`).","cause":"This typically happens if you are not using `BrowserRouter` or if the `id` of the target element does not exactly match the hash fragment in the `to` prop.","error":"HashLink is not scrolling to the correct element or not scrolling at all."},{"fix":"Ensure both the path and the hash fragment in the `to` prop of `NavHashLink` exactly match the current URL for the active styles to apply.","cause":"Unlike `NavLink`, `NavHashLink` requires both the path *and* the hash fragment to match for the link to be considered active by default.","error":"NavHashLink's `activeClassName` or `activeStyle` is not being applied when the hash fragment matches."}],"ecosystem":"npm"}