react-hash-scroll
v1.4.7
Customizable React components for hash scrolling with refs (TS supported)
0/weekUpdated 3 years agoMITUnpacked: 85.5 KB
Published by Yash Totale
npm install react-hash-scroll
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:
``shell`
npm install --save react-hash-scroll
Using yarn:
`shell`
yarn add react-hash-scroll
Using unpkg:
`html
`
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
$3
#### Summary
Scrolls to the child element when the specified hash is present in the url
#### Demo
#### Props
hash
- Required
- The hash%20in,specific%20subsection%20of%20that%20document.>) 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
`javascript
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 (
Element #2
Hello! (This does not work! Neither does <>Hello!) Children must be elements!
);
};
const HashChild = React.forwardRef((props, ref)) => ( // Must forward refs for custom HashScroll children
{props.children}
)
`
---
$3
#### 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
- 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 "#"
- Applies to all hashes unless overridden by a ref with options
- Applies to all hashes unless overridden by a ref with options
- Applies to all hashes unless overridden by a ref with options
- Applies to all hashes unless overridden by a ref with options
#### Example
javascript
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 (
"#div": ref1,
"#heading": [ref2, { behavior: "smooth" }],
"#paragraph": [
ref3,
{ position: "start", requiredPathname: ["/docs", "/contact"] },
],
}}
requiredPathname="/docs"
/>
Element #1
Element #2
Element #3
);
};
`---
$3
#### Summary
Scrolls to a corresponding child element when one of the hashes is present in the url
#### Demo
#### Props
- Required
- Array of hashes or hashes with scroll options (behavior, position, requiredPathname, scrollFunc)
- Hashes can include or exclude leading "#"
- Type:
- Required
- Number of children should equal the number of hashes
- Type:
#### Example
javascript
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 (
"#div",
{ hash: "#heading", behavior: "smooth" },
{ hash: "#paragraph", position: "end" },
]}
requiredPathname={["/login", "/signup"]}
>
Element #1
Element #2
Element #3
);
};
`---
Hooks
$3
#### Summary
Creates a ref that scrolls to its assigned element when a specified hash is present in the url
#### Demo
#### Params
- Required
- The hash that should trigger scroll
- Can include or exclude leading "#"
- Type:
- Examples:
- "#example"
- "example"- Object specifying optional scroll options
#### Example
javascript
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 (
options={{
behavior: "smooth",
}}
>
Element #1
Element #2
Element #3
);
};
const Example = ({ children, hash, options }) => {
const scrollRef = useHashScroll(hash, options); //options is optional
return
Scrolled to when the hash is in the url;
};
`---
Reused Props
Props that are used by multiple components
$3
- The behavior of the scroll
- Note: not all browsers have implemented options for
(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$3
- 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
$3
- 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[]$3
- 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:
---
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)
---
---
---
---
---
?label=Website%20Deploy%20%28Push%29&style=flat-square&logo=github&labelColor=000000&logoColor=FFFFF)
