React Hash Scroll

   

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