Table Of Contents

• Installation
• Why this one
• Website
• 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
• More Info (Badges)

Installation

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

Why this one

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

Website

The website compiles all the information and demos on this library in one easy-to-access place.

Components

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

HashScroll

Summary

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

Demo

Props

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

Example

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>
)

MultiHash

Summary

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

Demo

Props

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

Example

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>
  );
};

ChildrenHash

Summary

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

Demo

Props

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

Example

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>
  );
};

Hooks

useHashScroll

Summary

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

Demo

Params

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

Example

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>;
};

Reused Props

Props that are used by multiple components

behavior

• 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

position

• 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

requiredPathname

• 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[]

scrollFunc

• 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

Contributing

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

Check out first contributions if you are new to contributing

More Info (Badges)