Skip to content

Commit aeb89bf

Browse files
mmalfertheinermmalfertheiner
committed
update docs
1 parent 80589f3 commit aeb89bf

7 files changed

Lines changed: 158 additions & 95 deletions

‎readme.md‎

Lines changed: 128 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,18 @@
11
React Pagination
22
=============
33

4-
This package includes pagination hooks for React.
4+
This package includes pagination hooks for React. The hooks support saving the search and pagination values in local state or in the browser URL.
55

66
## Table of content
77

88
- [Usage](#usage)
9+
- [useSearch](#usesearch)
10+
- [usePagination](#usepagination)
11+
- [useSearchAndPagination](#usesearchandpagination)
12+
- [Supported Implementations](#supported-implementations)
913
- [In Memory Pagination](#in-memory-pagination)
10-
- [Router based pagination](#router-based-pagination)
14+
- [React-Router based pagination](#router-based-pagination)
15+
- [NextJS Router based pagination](#nextjs-router-based-pagination)
1116
- [Build & Publish](#build--publish)
1217
- [Information](#information)
1318

@@ -21,55 +26,138 @@ npm install @aboutbits/react-pagination
2126

2227
Second, you can make use of the different hooks.
2328

24-
### In Memory Pagination
29+
- [useSearch](#usesearch)
30+
- [usePagination](#usepagination)
31+
- [useSearchAndPagination](#usesearchandpagination)
32+
33+
### useSearch
2534

26-
Use this pagination hook if you want to keep track of the pagination in memory. This is very handy for dialogs.
35+
This hook saves the value of your search input and lets you change it or clear it.
36+
37+
```tsx
38+
39+
import { useSearch } from '@aboutbits/react-pagination/nextRouterPagination'
40+
41+
const users = [
42+
'Alex', 'Nadia', 'Natan', 'Marie', 'Moritz'
43+
]
44+
45+
function UserList() {
46+
const { search, searchActions } = useSearch()
47+
48+
return (
49+
<div>
50+
<input onChange={searchActions.search} />
51+
52+
<ul>
53+
{users
54+
.filter(user => user.startsWith(search))
55+
.map(user => <li>{user}</li>)}
56+
</ul>
57+
</div>
58+
)
59+
}
60+
```
61+
62+
### usePagination
63+
64+
This hook saves the value of your current page and lets you change it or clear it.
2765

2866
```tsx
29-
import { ReactElement } from "react";
30-
import { useSearchAndPaginationInMemory } from '@aboutbits/react-pagination'
3167

32-
function UsersDialog(): ReactElement {
68+
import { usePagination } from '@aboutbits/react-pagination/nextRouterPagination"
69+
70+
const users = [
71+
['Alex', 'Nadia'],
72+
['Natan', 'Marie'],
73+
['Moritz', 'Franz']
74+
]
75+
76+
function UserList() {
77+
const { page, size, paginationActions } = usePagination()
78+
79+
return (
80+
<div>
81+
<select onSelect={paginationActions.setPage}>
82+
<option value={0}>First Page</option>
83+
<option value={1}>Second Page</option>
84+
<option value={2}>Third Page</option>
85+
</select>
86+
87+
<ul>
88+
{users[page]
89+
.map(user => <li>{user}</li>)}
90+
</ul>
91+
</div>
92+
)
93+
}
94+
```
3395

34-
const {
35-
page,
36-
size,
37-
search,
38-
searchActions,
39-
paginationActions,
40-
} = useSearchAndPaginationInMemory()
96+
### useSearchAndPagination
97+
98+
This hook supports the combination of a search value and pagination.
99+
The `clear` function clears the search value and resets the page to the first page.
100+
101+
```tsx
102+
import { useSearchAndPagination } from '@aboutbits/react-pagination/nextRouterPagination'
103+
104+
const users = [
105+
'Alex', 'Simon', 'Natan', 'Nadia', 'Moritz', 'Marie'
106+
]
107+
108+
function UserList() {
109+
const { page, size, search, searchActions, paginationActions } = useSearchAndPagination()
41110

42111
return (
43-
<Dialog>
44-
<DialogSelectHeader
45-
title="Users"
46-
search={search}
47-
searchActions={searchActions}
48-
/>
49-
<AsyncView
50-
{...useSearchUsers({
51-
page: page,
52-
size: size,
53-
query: search,
54-
})}
55-
renderSuccess={(data) => (
56-
<DisplayData
57-
data={data}
58-
paginationActions={paginationActions}
59-
/>
60-
)}
61-
renderLoading={<LoadingList />}
62-
renderError={(error) => (
63-
<Error error={error} />
64-
)}
65-
/>
66-
</Dialog>
112+
<div>
113+
<input onChange={searchActions.search} />
114+
<button onClick={searchActions.clear}>Clear Input</button>
115+
<select onSelect={paginationActions.setPage}>
116+
<option value={0}>First Page</option>
117+
<option value={1}>Second Page</option>
118+
</select>
119+
120+
<ul>
121+
{users.filter(user => user.startsWith(search))
122+
.slice(page, page + size)
123+
.map(user => <li>{user}</li>)}
124+
</ul>
125+
</div>
67126
)
68-
69127
}
70128
```
71129

72-
### Router based pagination
130+
## Supported implementations
131+
132+
This package includes 3 different implementations of the above hooks.
133+
- [In Memory](#in-memory-pagination)
134+
- [React Router](#react-router-based-pagination)
135+
- [NextJS Router](#nextjs-router-based-pagination)
136+
137+
### In Memory Pagination
138+
139+
Use this pagination hook if you want to keep track of the pagination in memory.
140+
This is very handy for dialogs.
141+
142+
```tsx
143+
import { useSearchAndPaginationInMemory } from '@aboutbits/react-pagination'
144+
```
145+
146+
### React-Router based pagination
147+
148+
These are specific hooks for applications that use [React Router](https://reactrouter.com/) for routing.
149+
150+
```tsx
151+
import { useSearchAndPagination } from '@aboutbits/react-pagination/reactRouterPagination'
152+
```
153+
154+
### NextJS Router based pagination
155+
156+
These are specific hooks for applications that use [NextJS Router](https://nextjs.org/docs/api-reference/next/router) for routing.
157+
158+
```tsx
159+
import { useSearchAndPagination } from '@aboutbits/react-pagination/nextRouterPagination'
160+
```
73161

74162
## Build & Publish
75163

‎src/__test__/inMemoryPagination.test.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
import { act, renderHook } from '@testing-library/react-hooks'
2-
import { useSearchAndPaginationInMemory } from '../inMemoryPagination'
2+
import { useSearchAndPagination } from '../inMemoryPagination'
33

44
test('should initialize pagination', () => {
5-
const { result } = renderHook(() => useSearchAndPaginationInMemory())
5+
const { result } = renderHook(() => useSearchAndPagination())
66

77
expect(result.current.page).toBe(0)
88
expect(result.current.search).toBe('')
99
expect(result.current.size).toBe(15)
1010
})
1111

1212
test('should change page', () => {
13-
const { result } = renderHook(() => useSearchAndPaginationInMemory())
13+
const { result } = renderHook(() => useSearchAndPagination())
1414

1515
act(() => {
1616
result.current.paginationActions.setPage(2)
@@ -20,7 +20,7 @@ test('should change page', () => {
2020
})
2121

2222
test('should change search', () => {
23-
const { result } = renderHook(() => useSearchAndPaginationInMemory())
23+
const { result } = renderHook(() => useSearchAndPagination())
2424

2525
act(() => {
2626
result.current.searchActions.search('Max')
@@ -30,7 +30,7 @@ test('should change search', () => {
3030
})
3131

3232
test('on search change -> page should be reset', () => {
33-
const { result } = renderHook(() => useSearchAndPaginationInMemory())
33+
const { result } = renderHook(() => useSearchAndPagination())
3434

3535
act(() => {
3636
result.current.paginationActions.setPage(2)
@@ -47,7 +47,7 @@ test('on search change -> page should be reset', () => {
4747
})
4848

4949
test('clear pagination should reset search and page', () => {
50-
const { result } = renderHook(() => useSearchAndPaginationInMemory())
50+
const { result } = renderHook(() => useSearchAndPagination())
5151

5252
act(() => {
5353
result.current.searchActions.search('Max')

‎src/__test__/nextRouterPagination.test.tsx‎

Lines changed: 6 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3,24 +3,20 @@ import React from 'react'
33
import { act, renderHook } from '@testing-library/react-hooks'
44
import router from 'next/router'
55

6-
import { useSearchAndPaginationQueryUrlParameters } from '../nextRouterPagination'
6+
import { useSearchAndPagination } from '../nextRouterPagination'
77

88
jest.mock('next/router', () => require('next-router-mock'))
99

1010
test('should initialize pagination', () => {
11-
const { result } = renderHook(() =>
12-
useSearchAndPaginationQueryUrlParameters()
13-
)
11+
const { result } = renderHook(() => useSearchAndPagination())
1412

1513
expect(result.current.page).toBe(0)
1614
expect(result.current.search).toBe('')
1715
expect(result.current.size).toBe(15)
1816
})
1917

2018
test('should change page', () => {
21-
const { result } = renderHook(() =>
22-
useSearchAndPaginationQueryUrlParameters()
23-
)
19+
const { result } = renderHook(() => useSearchAndPagination())
2420

2521
act(() => {
2622
result.current.paginationActions.setPage(2)
@@ -31,9 +27,7 @@ test('should change page', () => {
3127
})
3228

3329
test('should change search', () => {
34-
const { result } = renderHook(() =>
35-
useSearchAndPaginationQueryUrlParameters()
36-
)
30+
const { result } = renderHook(() => useSearchAndPagination())
3731

3832
act(() => {
3933
result.current.searchActions.search('Max')
@@ -44,9 +38,7 @@ test('should change search', () => {
4438
})
4539

4640
test('on search change -> page should be reset', () => {
47-
const { result } = renderHook(() =>
48-
useSearchAndPaginationQueryUrlParameters()
49-
)
41+
const { result } = renderHook(() => useSearchAndPagination())
5042

5143
act(() => {
5244
result.current.paginationActions.setPage(2)
@@ -66,9 +58,7 @@ test('on search change -> page should be reset', () => {
6658
})
6759

6860
test('clear pagination should reset search and page', () => {
69-
const { result } = renderHook(() =>
70-
useSearchAndPaginationQueryUrlParameters()
71-
)
61+
const { result } = renderHook(() => useSearchAndPagination())
7262

7363
act(() => {
7464
result.current.searchActions.search('Max')

‎src/__test__/reactRouterPagination.test.tsx‎

Lines changed: 6 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,20 @@
11
import React from 'react'
22
import { act, renderHook } from '@testing-library/react-hooks'
33
import { BrowserRouter as Router } from 'react-router-dom'
4-
import { useSearchAndPaginationQueryUrlParameters } from '../reactRouterPagination'
4+
import { useSearchAndPagination } from '../reactRouterPagination'
55

66
const wrapper: React.FC = ({ children }) => <Router>{children}</Router>
77

88
test('should initialize pagination', () => {
9-
const { result } = renderHook(
10-
() => useSearchAndPaginationQueryUrlParameters(),
11-
{ wrapper }
12-
)
9+
const { result } = renderHook(() => useSearchAndPagination(), { wrapper })
1310

1411
expect(result.current.page).toBe(0)
1512
expect(result.current.search).toBe('')
1613
expect(result.current.size).toBe(15)
1714
})
1815

1916
test('should change page', () => {
20-
const { result } = renderHook(
21-
() => useSearchAndPaginationQueryUrlParameters(),
22-
{ wrapper }
23-
)
17+
const { result } = renderHook(() => useSearchAndPagination(), { wrapper })
2418

2519
act(() => {
2620
result.current.paginationActions.setPage(2)
@@ -31,10 +25,7 @@ test('should change page', () => {
3125
})
3226

3327
test('should change search', () => {
34-
const { result } = renderHook(
35-
() => useSearchAndPaginationQueryUrlParameters(),
36-
{ wrapper }
37-
)
28+
const { result } = renderHook(() => useSearchAndPagination(), { wrapper })
3829

3930
act(() => {
4031
result.current.searchActions.search('Max')
@@ -45,10 +36,7 @@ test('should change search', () => {
4536
})
4637

4738
test('on search change -> page should be reset', () => {
48-
const { result } = renderHook(
49-
() => useSearchAndPaginationQueryUrlParameters(),
50-
{ wrapper }
51-
)
39+
const { result } = renderHook(() => useSearchAndPagination(), { wrapper })
5240

5341
act(() => {
5442
result.current.paginationActions.setPage(2)
@@ -66,10 +54,7 @@ test('on search change -> page should be reset', () => {
6654
})
6755

6856
test('clear pagination should reset search and page', () => {
69-
const { result } = renderHook(
70-
() => useSearchAndPaginationQueryUrlParameters(),
71-
{ wrapper }
72-
)
57+
const { result } = renderHook(() => useSearchAndPagination(), { wrapper })
7358

7459
act(() => {
7560
result.current.searchActions.search('Max')

‎src/inMemoryPagination.tsx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { useState, useCallback, useMemo } from 'react'
22
import { UseSearchAndPagination } from './types'
33

4-
const useSearchAndPaginationInMemory = (): UseSearchAndPagination => {
4+
const useSearchAndPagination = (): UseSearchAndPagination => {
55
const initialState = useMemo(
66
() => ({
77
page: 0,
@@ -50,4 +50,4 @@ const useSearchAndPaginationInMemory = (): UseSearchAndPagination => {
5050
}
5151
}
5252

53-
export { useSearchAndPaginationInMemory }
53+
export { useSearchAndPagination }

0 commit comments

Comments
 (0)