Skip to content
This repository was archived by the owner on May 1, 2025. It is now read-only.

Commit af14f78

Browse files
YashTotaleYashTotale
authored
Merge pull request #3 from YashTotale/children-hash
ChildrenHash component
2 parents 4cfd2a6 + 18862ae commit af14f78

File tree

15 files changed

+424
-175
lines changed

15 files changed

+424
-175
lines changed

‎CHANGELOG.md‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,30 +8,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88
**Table of Contents**
99

1010
- [[Unreleased]](#unreleased)
11+
- [[v1.3.0] - (2020-11-27)](#v130---2020-11-27)
12+
- [Added](#added)
1113
- [[v1.2.3] - (2020-11-26)](#v123---2020-11-26)
1214
- [Removed](#removed)
1315
- [[v1.2.2] - (2020-11-26)](#v122---2020-11-26)
1416
- [Fixed](#fixed)
1517
- [[v1.2.1] - (2020-11-26)](#v121---2020-11-26)
1618
- [Fixed](#fixed-1)
1719
- [[v1.2.0] - (2020-11-26)](#v120---2020-11-26)
18-
- [Added](#added)
20+
- [Added](#added-1)
1921
- [Changed](#changed)
2022
- [Dependencies](#dependencies)
2123
- [[v1.1.0] - (2020-11-24)](#v110---2020-11-24)
22-
- [Added](#added-1)
24+
- [Added](#added-2)
2325
- [Changed](#changed-1)
2426
- [[v1.0.2] - (2020-11-23)](#v102---2020-11-23)
2527
- [Changed](#changed-2)
2628
- [[1.0.1] - (2020-11-23)](#101---2020-11-23)
27-
- [Added](#added-2)
29+
- [Added](#added-3)
2830
- [Fixed](#fixed-2)
2931
- [[1.0.0] - (2020-11-23)](#100---2020-11-23)
3032

3133
## [Unreleased]
3234

3335
---
3436

37+
## [v1.3.0] - (2020-11-27)
38+
39+
### Added
40+
41+
- ChildrenHash component
42+
43+
---
44+
3545
## [v1.2.3] - (2020-11-26)
3646

3747
### Removed

‎README.md‎

Lines changed: 143 additions & 139 deletions
Original file line numberDiff line numberDiff line change
@@ -17,20 +17,21 @@ _Table Of Contents_
1717

1818
- [Installation](#installation)
1919
- [Why this one](#why-this-one)
20-
- [Usage](#usage)
21-
- [HashScroll](#hashscroll)
22-
- [MultiHash](#multihash)
23-
- [Component API](#component-api)
20+
- [Components](#components)
2421
- [Reused Props](#reused-props)
2522
- [behavior](#behavior)
2623
- [position](#position)
2724
- [requiredPathname](#requiredpathname)
2825
- [scrollFunc](#scrollfunc)
29-
- [HashScroll](#hashscroll-1)
30-
- [hash](#hash)
31-
- [children](#children)
32-
- [MultiHash](#multihash-1)
33-
- [hashes](#hashes)
26+
- [HashScroll](#hashscroll)
27+
- [Props](#props)
28+
- [Example](#example)
29+
- [MultiHash](#multihash)
30+
- [Props](#props-1)
31+
- [Example](#example-1)
32+
- [ChildrenHash](#childrenhash)
33+
- [Props](#props-2)
34+
- [Example](#example-2)
3435
- [Contributing](#contributing)
3536
- [More Info (Badges)](#more-info-badges)
3637

@@ -72,82 +73,14 @@ There are a lot of hash scrolling React libraries out there, so why should you p
7273
- Most other libraries rely on scrolling by id, whereas this library relies on ref scrolling, making it more robust for large projects
7374
- This library offers built-in [TypeScript](https://www.typescriptlang.org/) support
7475
- Extensive testing makes this library more dependable
75-
- The components that this library provides are very customizable, making it more likely that they will fit your use case
76+
- This library provides components that are very customizable, making it more likely that they will fit your use case
7677

7778
---
7879

79-
## Usage
80+
## Components
8081

8182
**Note**: [react-router-dom](https://reactrouter.com/web/) is required as a peer dependency and all components must be wrapped in a [Router](https://reactrouter.com/web/api/BrowserRouter)
8283

83-
### HashScroll
84-
85-
- In this example, the div with text "Element #1" will be scrolled to the center of the page when the url hash is "#hash1".
86-
- The div with text "Element #2" will only be scrolled to when both the hash and the pathname are "#hash2" and "/docs", respectively.
87-
88-
```javascript
89-
import React from "react";
90-
import { BrowserRouter } from "react-router-dom"; //Can use HashRouter or MemoryRouter as well
91-
import { HashScroll } from "react-hash-scroll";
92-
93-
const App = () => {
94-
return (
95-
<BrowserRouter>
96-
<HashScroll hash="#hash1" position="center">
97-
<HashChild>Element #1</HashChild>
98-
</HashScroll>
99-
<HashScroll hash="#hash2" requiredPathname="/docs">
100-
<div>Element #2</div>
101-
</HashScroll>
102-
</BrowserRouter>
103-
);
104-
};
105-
106-
const HashChild = React.forwardRef((props, ref)) => ( // Must forward refs for custom HashScroll children
107-
<div ref={ref}>{props.children}</div>
108-
)
109-
```
110-
111-
### MultiHash
112-
113-
In this example, the elements will only be scrolled to on the "/docs" page.
114-
115-
- The div with text "Element #1" will be scrolled to when the url hash is "#div".
116-
- Similarly, the h4 with text "Element #2" will be scrolled to smoothly when the hash is "#heading".
117-
- Finally, if the hash is "#paragraph", the p with text "Element #3" will be scrolled to the top of the page.
118-
119-
```javascript
120-
import React from "react";
121-
import { BrowserRouter } from "react-router-dom"; //Can use HashRouter or MemoryRouter as well
122-
import { MultiHash } from "react-hash-scroll";
123-
124-
const App = () => {
125-
const ref1 = React.createRef();
126-
const ref2 = React.createRef();
127-
const ref3 = React.createRef();
128-
129-
return (
130-
<BrowserRouter>
131-
<MultiHash
132-
hashes={{
133-
"#div": ref1,
134-
"#heading": [ref2, { behavior: "smooth" }],
135-
"#paragraph": [ref3, { position: "start" }],
136-
}}
137-
requiredPathname="/docs"
138-
/>
139-
<div ref={ref1}>Element #1</div>
140-
<h4 ref={ref2}>Element #2</h4>
141-
<p ref={ref3}>Element #3</p>
142-
</BrowserRouter>
143-
);
144-
};
145-
```
146-
147-
---
148-
149-
## Component API
150-
15184
### Reused Props
15285

15386
Props that are used by multiple components
@@ -189,11 +122,15 @@ Props that are used by multiple components
189122
- [position](#position): The defined scroll position for the element or the default position
190123
- Type: `(ref,`[`behavior`](#behavior)`,`[`position`](#position)`) => void`
191124

125+
---
126+
192127
### HashScroll
193128

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

196-
#### hash
131+
#### Props
132+
133+
`hash`
197134

198135
- **Required**
199136
- Type: `string`
@@ -203,95 +140,162 @@ Scrolls to child element when the specified hash is present in the url
203140
- "#example"
204141
- "example"
205142

206-
#### [behavior](#behavior) <!-- omit in toc -->
143+
[`behavior`](#behavior)
207144

208-
#### [position](#position) <!-- omit in toc -->
145+
[`position`](#position)
209146

210-
#### [requiredPathname](#requiredpathname) <!-- omit in toc -->
147+
[`requiredPathname`](#requiredpathname)
211148

212-
#### [scrollFunc](#scrollfunc) <!-- omit in toc -->
149+
[`scrollFunc`](#scrollfunc)
213150

214-
#### children
151+
`children`
215152

216153
- **Required**
217154
- Type: `ReactElement`
218155
- Must be a singular child (which **CANNOT** be text)
219156
- Custom children must forward refs to a dom element
220-
- Examples:
221157

222-
```javascript
223-
<HashScroll
224-
hash="#example"
225-
position="start"
226-
behavior="smooth"
227-
requiredPathname="/contact"
228-
>
229-
<div>Example</div>
230-
</HashScroll>
231-
```
232-
233-
```javascript
234-
<HashScroll
235-
hash="#example"
236-
position="nearest"
237-
behavior="auto"
238-
requiredPathname=["/docs/api", "/home"]
239-
>
240-
<CustomChild /> //This component MUST forward ref to a dom element
241-
</HashScroll>
242-
```
243-
244-
```javascript
245-
<HashScroll hash="#example" position="end">
246-
Hello! //This does not work! Neither does <>Hello!</>
247-
</HashScroll>
248-
```
158+
#### Example
159+
160+
```javascript
161+
import React from "react";
162+
import { BrowserRouter } from "react-router-dom"; //Can use HashRouter or MemoryRouter as well
163+
import { HashScroll } from "react-hash-scroll";
164+
165+
const App = () => {
166+
return (
167+
<BrowserRouter>
168+
<HashScroll hash="#hash1" position="center">
169+
<HashChild>Element #1</HashChild>
170+
</HashScroll>
171+
<HashScroll hash="#hash2" requiredPathname="/docs">
172+
<div>Element #2</div>
173+
</HashScroll>
174+
<HashScroll hash="#example" position="end">
175+
Hello! (This does not work! Neither does <>Hello!</>) Children must be elements!
176+
</HashScroll>
177+
</BrowserRouter>
178+
);
179+
};
180+
181+
const HashChild = React.forwardRef((props, ref)) => ( // Must forward refs for custom HashScroll children
182+
<div ref={ref}>{props.children}</div>
183+
)
184+
```
185+
186+
---
249187

250188
### MultiHash
251189

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

254-
#### hashes
192+
#### Props
193+
194+
`hashes`
255195

256196
- **Required**
257-
- An object specifying the hashes and the refs they correspond to
197+
- An object specifying the hashes and the refs or refs with options ([behavior](#behavior), [position](#position), [requiredPathname](#requiredpathname), [scrollFunc](#scrollfunc)) they correspond to
258198
- Hashes can include or exclude leading "#"
259-
- Each hash corresponds to a ref or a ref with options ([behavior](#behavior), [position](#position), [requiredPathname](#requiredpathname), [scrollFunc](#scrollfunc))
260-
- Example:
261-
262-
```javascript
263-
const ref1 = createRef();
264-
const ref2 = createRef();
265-
const hashes = {
266-
hash1: ref1,
267-
"#hash2": [
268-
ref2,
269-
{
270-
behavior: "auto",
271-
requiredPathname: ["/docs", "/contact"],
272-
},
273-
],
274-
};
275-
276-
return <MultiHash hashes={hashes} />;
277-
```
278-
279-
#### [behavior](#behavior) <!-- omit in toc -->
199+
200+
[`behavior`](#behavior)
280201

281202
- Applies to all hashes unless overriden by a ref with options
282203

283-
#### [position](#position) <!-- omit in toc -->
204+
[`position`](#position)
284205

285206
- Applies to all hashes unless overriden by a ref with options
286207

287-
#### [requiredPathname](#requiredpathname) <!-- omit in toc -->
208+
[`requiredPathname`](#requiredpathname)
288209

289210
- Applies to all hashes unless overriden by a ref with options
290211

291-
#### [scrollFunc](#scrollfunc) <!-- omit in toc -->
212+
[`scrollFunc`](#scrollfunc)
292213

293214
- Applies to all hashes unless overriden by a ref with options
294215

216+
#### Example
217+
218+
```javascript
219+
import React from "react";
220+
import { BrowserRouter } from "react-router-dom"; //Can use HashRouter or MemoryRouter as well
221+
import { MultiHash } from "react-hash-scroll";
222+
223+
const App = () => {
224+
const ref1 = React.createRef();
225+
const ref2 = React.createRef();
226+
const ref3 = React.createRef();
227+
228+
return (
229+
<BrowserRouter>
230+
<MultiHash
231+
hashes={{
232+
"#div": ref1,
233+
"#heading": [ref2, { behavior: "smooth" }],
234+
"#paragraph": [
235+
ref3,
236+
{ position: "start", requiredPathname: ["/docs", "/contact"] },
237+
],
238+
}}
239+
requiredPathname="/docs"
240+
/>
241+
<div ref={ref1}>Element #1</div>
242+
<h4 ref={ref2}>Element #2</h4>
243+
<p ref={ref3}>Element #3</p>
244+
</BrowserRouter>
245+
);
246+
};
247+
```
248+
249+
---
250+
251+
### ChildrenHash
252+
253+
Scrolls to corresponding child element when one of the hashes is present in the url
254+
255+
#### Props
256+
257+
`hashes`
258+
259+
- **Required**
260+
- Array of hashes or hashes with scroll options ([behavior](#behavior), [position](#position), [requiredPathname](#requiredpathname), [scrollFunc](#scrollfunc))
261+
- Hashes can include or exclude leading "#"
262+
- Length should be equal to children length
263+
264+
[`behavior`](#behavior)
265+
266+
[`position`](#position)
267+
268+
[`requiredPathname`](#requiredpathname)
269+
270+
[`scrollFunc`](#scrollfunc)
271+
272+
#### Example
273+
274+
```javascript
275+
import React from "react";
276+
import { BrowserRouter } from "react-router-dom"; //Can use HashRouter or MemoryRouter as well
277+
import { ChildrenHash } from "react-hash-scroll";
278+
279+
const App = () => {
280+
return (
281+
<BrowserRouter>
282+
<ChildrenHash
283+
hashes={[
284+
"#div",
285+
{ hash: "#heading", behavior: "smooth" },
286+
{ hash: "#paragraph", position: "end" },
287+
]}
288+
requiredPathname={["/login", "/signup"]}
289+
>
290+
<div ref={ref1}>Element #1</div>
291+
<h4 ref={ref2}>Element #2</h4>
292+
<p ref={ref3}>Element #3</p>
293+
</ChildrenHash>
294+
</BrowserRouter>
295+
);
296+
};
297+
```
298+
295299
---
296300

297301
## Contributing

0 commit comments

Comments
 (0)