React-hash-scroll NPM

Table Of Contents

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

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

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

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