Table Of Contents

• Installation
• Why this one
• Components
  • HashScroll
    • Summary
    • Demo
    • Props
    • Example
  • MultiHash
    • Summary
    • Demo
    • Props
    • Example
  • ChildrenHash
    • Summary
    • Demo
    • Props
    • Example
• Hooks
  • useHashScroll
    • Summary
    • Demo
    • Params
    • Example
• Reused Props
  • behavior
  • position
  • requiredPathname
  • scrollFunc
• Contributing

Using npm:

npm install --save react-hash-scroll

Using yarn:

yarn add react-hash-scroll

Using unpkg:

<!-- These 3 are required as peer dependencies --> <script src="https://unpkg.com/react/umd/react.production.min.js"></script> <script src="https://unpkg.com/react-dom/umd/react-dom.production.min.js"></script> <script src="https://unpkg.com/react-router-dom/umd/react-router-dom.min.js"></script> <script src="https://unpkg.com/react-hash-scroll/umd/react-hash-scroll.min.js"></script>

You can then access the library as window.ReactHashScroll

There are a lot of hash scrolling React libraries out there, so why should you pick this one?

• Most other libraries rely on scrolling by id, whereas React Hash Scroll relies on ref scrolling, making it more robust for large projects
• React Hash Scroll offers built-in TypeScript support
• Extensive testing makes React Hash Scroll more dependable
• Components provided by React Hash Scroll are very customizable, making it more likely that they will fit your use case

Note: react-router-dom is required as a peer dependency and all components must be wrapped in a Router

Scrolls to the child element when the specified hash is present in the url

hash

• Required
• The hash that should trigger scroll to the element
• Can include or exclude leading "#"
• Type: string
• Examples:
  • "#example"
  • "example"

children

• Required
• Must be a singular child (which MUST be a DOM element and CANNOT be text)
• Custom children must forward refs to a DOM element
• Type: ReactElement

behavior

position

requiredPathname

scrollFunc

import React from "react"; import { BrowserRouter } from "react-router-dom"; //Can use HashRouter or MemoryRouter as well import { HashScroll } from "react-hash-scroll"; const App = () => { return ( <BrowserRouter> <HashScroll hash="#hash1" position="center"> <HashChild>Element #1</HashChild> </HashScroll> <HashScroll hash="#hash2" requiredPathname="/docs"> <div>Element #2</div> </HashScroll> <HashScroll hash="#example" position="end"> Hello! (This does not work! Neither does <>Hello!</>) Children must be elements! </HashScroll> </BrowserRouter> ); }; const HashChild = React.forwardRef((props, ref)) => ( // Must forward refs for custom HashScroll children <div ref={ref}>{props.children}</div> )

Component that pairs hashes with refs and scrolls to a corresponding ref when one of the hashes is present in the url

hashes

• Required
• An object specifying the hashes and the refs or refs with options (behavior, position, requiredPathname, scrollFunc) they correspond to
• Hashes can include or exclude leading "#"

behavior

• Applies to all hashes unless overridden by a ref with options

position

• Applies to all hashes unless overridden by a ref with options

requiredPathname

• Applies to all hashes unless overridden by a ref with options

scrollFunc

• Applies to all hashes unless overridden by a ref with options

import React from "react"; import { BrowserRouter } from "react-router-dom"; //Can use HashRouter or MemoryRouter as well import { MultiHash } from "react-hash-scroll"; const App = () => { const ref1 = React.createRef(); const ref2 = React.createRef(); const ref3 = React.createRef(); return ( <BrowserRouter> <MultiHash hashes={{ "#div": ref1, "#heading": [ref2, { behavior: "smooth" }], "#paragraph": [ ref3, { position: "start", requiredPathname: ["/docs", "/contact"] }, ], }} requiredPathname="/docs" /> <div ref={ref1}>Element #1</div> <h4 ref={ref2}>Element #2</h4> <p ref={ref3}>Element #3</p> </BrowserRouter> ); };

Scrolls to a corresponding child element when one of the hashes is present in the url

hashes

• Required
• Array of hashes or hashes with scroll options (behavior, position, requiredPathname, scrollFunc)
• Hashes can include or exclude leading "#"
• Type: string[] | BaseScrollOptionsWithHash[]

children

• Required
• Number of children should equal the number of hashes
• Type: ReactElement[]

behavior

position

requiredPathname

scrollFunc

import React from "react"; import { BrowserRouter } from "react-router-dom"; //Can use HashRouter or MemoryRouter as well import { ChildrenHash } from "react-hash-scroll"; const App = () => { return ( <BrowserRouter> <ChildrenHash hashes={[ "#div", { hash: "#heading", behavior: "smooth" }, { hash: "#paragraph", position: "end" }, ]} requiredPathname={["/login", "/signup"]} > <div>Element #1</div> <h4>Element #2</h4> <p>Element #3</p> </ChildrenHash> </BrowserRouter> ); };

Creates a ref that scrolls to its assigned element when a specified hash is present in the url

hash

• Required
• The hash that should trigger scroll
• Can include or exclude leading "#"
• Type: string
• Examples:
  • "#example"
  • "example"

options

• Object specifying optional scroll options

  • behavior

  • position

  • requiredPathname

  • scrollFunc

import React from "react"; import { BrowserRouter } from "react-router-dom"; //Can use HashRouter or MemoryRouter as well import { useHashScroll } from "react-hash-scroll"; const App = () => { return ( <BrowserRouter> <Example hash="#element1" options={{ behavior: "smooth", }} > Element #1 </Example> <Example hash="#element2">Element #2</Example> <Example hash="#element3">Element #3</Example> </BrowserRouter> ); }; const Example = ({ children, hash, options }) => { const scrollRef = useHashScroll(hash, options); //options is optional return <div ref={scrollRef}>Scrolled to when the hash is in the url</div>; };

Props that are used by multiple components

• The behavior of the scroll
• Note: not all browsers have implemented options for Element.scrollIntoView (which is what React Hash Scroll uses internally)
  • See MDN and Can I Use for a comprehensive list
  • There is also a browser polyfill for smooth scrolling which you can install separately so smooth scrolling will work in all browsers
• Type:
  • "smooth": Smooth scroll (Default)
  • "auto": Instant scroll

• The position of the element on the page after it is scrolled to
• Like behavior, some browsers don't support scrollIntoView options yet, so this property may not work on all browsers.
• Type:
  • "center": Element will scroll to center of page (Default)
  • "end": Element will scroll to bottom of page
  • "start": Element will scroll to top of page
  • "nearest": Element will scroll to center/end/start depending on which one is closest

• Only scroll on a specific pathname(s)
• Note: "/" matches to the website name with no pathname
• Don't end pathnames with "/" (Ex. "/test/")
• For example, to only scroll on:
  • /home/contact: "/home/contact"
  • /docs or /features: ["/docs", "/features"]
• Type: string | string[]

• A custom scroll function that overrides the default scrollIntoView function used by React Hash Scroll
• Parameters:
  • ref: The ref object that contains the target element
  • behavior: The defined scroll behavior for the element or the default behavior
  • position: The defined scroll position for the element or the default position
• Type: (ref,behavior,position) => void

• Go to the github repository
• Open a new issue or pull request

Check out first contributions if you are new to contributing