Skip to content

Commit 8461aef

Browse files
author
devgioele
committed
update readme
1 parent 20a6654 commit 8461aef

1 file changed

Lines changed: 139 additions & 89 deletions

File tree

‎readme.md‎

Lines changed: 139 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
React Pagination
2-
=============
1+
# React Pagination
32

43
[![npm package](https://badge.fury.io/js/%40aboutbits%2Freact-pagination.svg)](https://badge.fury.io/js/%40aboutbits%2Freact-pagination)
54
[![license](https://img.shields.io/github/license/aboutbits/react-pagination)](https://github.com/aboutbits/react-pagination/blob/main/license.md)
@@ -10,129 +9,180 @@ state or in the browser URL.
109
## Table of content
1110

1211
- [Usage](#usage)
13-
- [useQueryAndPagination](#usequeryandpagination)
14-
- [Supported Implementations](#supported-implementations)
15-
- [In Memory Pagination](#in-memory-pagination)
16-
- [React-Router based pagination](#react-router-based-pagination)
17-
- [NextJS Router based pagination](#nextjs-router-based-pagination)
12+
- [useQuery](#usequery)
13+
- [usePagination](#usepagination)
14+
- [useQueryAndPagination](#usequeryandpagination)
1815
- [Build & Publish](#build--publish)
1916
- [Information](#information)
2017

2118
## Usage
2219

23-
First, you have to install the package:
20+
Install the package:
2421

25-
```bash
22+
```sh
2623
npm install @aboutbits/react-pagination
2724
```
2825

29-
Second, you can make use of the `useQueryAndPagination` hook. This package implements 3 versions of this hook:
26+
There are a variety of entry points from which to import the hooks `useQuery`, `usePagiation` and `useQueryAndPagination`:
3027

31-
- [In Memory](#in-memory-pagination): Use this hook where you don't want to modify browser history. e.g. Dialogs
32-
- [React Router](#react-router-based-pagination): Use this hook if you want to keep track of the state in the URL and
33-
your project is using React Router.
34-
- [NextJS Router](#nextjs-router-based-pagination): Use this hook if you want to keep track of the state in the URL and
35-
your project is using NextJS.
28+
- For the [Next.js](https://nextjs.org/) router:
29+
- `@aboutbits/react-pagination/next-router`
30+
- `@aboutbits/react-pagination/next-router/zod`
31+
- For [React Router](https://reactrouter.com):
32+
- `@aboutbits/react-pagination/react-router`
33+
- `@aboutbits/react-pagination/react-router/zod`
34+
- For an in-memory router that does not modify the browser history:
35+
- `@aboutbits/react-pagination/in-memory`
36+
- `@aboutbits/react-pagination/in-memory/zod`
3637

37-
### useQueryAndPagination
38+
The hooks exported from `@aboutbits/react-pagination/*/zod` are more convenient when using [zod](https://github.com/colinhacks/zod) for the validation of the query.
3839

39-
This hook supports the combination of query parameters and pagination and manages the state of the query parameter values and the
40-
pagination values.
40+
`useQueryAndPagination` merges the functionality of `useQuery` and `usePagination`. Changing the query resets the page, but changing the page does not reset the query.
4141

42-
#### The hook supports following configuration parameter object:
42+
Some examples follow, but we recommend having a look at the type definitions for more details about the API.
4343

44-
|value|type|default|description|
45-
|---|---|---|---|
46-
|indexType|IndexType|IndexType.ZERO_BASED|It defines whether the pagination is zero or one based.|
47-
|pageSize|number|15|Page size of the pagination.|
48-
|defaultQueryParameters/Record<string, string>|{}|It defines the default value for each query parameter. This is used to remove a query parameter from the URL and also to clear the query.
49-
50-
#### The hook returns the following object:
51-
52-
|value|type|description|
53-
|---|---|---|
54-
|queryParameters|object|values of your query parameters|
55-
|page|number|value of the current page|
56-
|size|number|max elements in a single page|
57-
|actions|object|object with 3 functions: updateQuery, setPage, clear|
58-
59-
#### Example usage with NextJS
44+
#### Example usage with Next.js
6045

6146
```tsx
62-
import { useQueryAndPagination } from '@aboutbits/react-pagination/dist/nextRouterPagination'
63-
64-
const users = [
65-
'Alex', 'Simon', 'Natan', 'Nadia', 'Moritz', 'Marie'
66-
]
67-
68-
function UserList() {
69-
const { page, size, queryParameters, actions } = useQueryAndPagination({pageSize: 2})
70-
71-
return (
72-
<div>
73-
<input onChange={(value) => actions.updateQuery({search: value})}/>
74-
<button onClick={() => actions.clear()}>Clear Input</button>
75-
<select onSelect={(value) => actions.setPage(value)}>
76-
<option value={0}>First Page</option>
77-
<option value={1}>Second Page</option>
78-
</select>
79-
80-
<ul>
81-
{users.filter(user => user.startsWith(queryParameters.search))
82-
.slice(page, page + size)
83-
.map(user => <li>{user}</li>)}
84-
</ul>
85-
</div>
86-
)
47+
import { Query } from '@aboutbits/react-pagination'
48+
import { useQueryAndPagination } from '@aboutbits/react-pagination/next-router'
49+
50+
const users = ['Alex', 'Simon', 'Natan', 'Nadia', 'Moritz', 'Marie']
51+
52+
const parseSearch = (query: Query) => {
53+
for (const [key, value] of Object.entries(query)) {
54+
if (key === 'search' && !Array.isArray(value)) {
55+
return { search: value }
56+
}
57+
}
58+
return {}
8759
}
88-
```
89-
90-
## Supported implementations
91-
92-
This package includes 3 different implementations of the above hook.
93-
94-
- [In Memory](#in-memory-pagination)
95-
- [React Router](#react-router-based-pagination)
96-
- [NextJS Router](#nextjs-router-based-pagination)
9760

98-
### In Memory Pagination
99-
100-
Use this pagination hook if you want to keep track of the pagination in memory. This is very handy for dialogs.
101-
102-
```tsx
103-
import { useQueryAndPagination } from '@aboutbits/react-pagination/dist/inMemoryPagination'
61+
export function UserList() {
62+
const { page, size, query, setQuery, setPage, resetQuery } =
63+
useQueryAndPagination({ search: '' }, parseSearch)
64+
65+
return (
66+
<div>
67+
<input
68+
value={query.search}
69+
onChange={(event) => setQuery({ search: event.target.value })}
70+
/>
71+
<button onClick={() => resetQuery()}>Clear Input</button>
72+
<select
73+
value={page}
74+
onChange={(event) => setPage(parseInt(event.target.value))}
75+
>
76+
<option value="0">First Page</option>
77+
<option value="1">Second Page</option>
78+
</select>
79+
<ul>
80+
{users
81+
.filter((user) =>
82+
user.toLowerCase().startsWith(query.search.toLowerCase())
83+
)
84+
.slice(page * size, (page + 1) * size)
85+
.map((user) => (
86+
<li key={user}>{user}</li>
87+
))}
88+
</ul>
89+
</div>
90+
)
91+
}
10492
```
10593

106-
### React-Router based pagination
107-
108-
These are specific hooks for applications that use [React Router](https://reactrouter.com/) for routing.
94+
### Example usage with React Router and zod
10995

11096
```tsx
111-
import { useQueryAndPagination } from '@aboutbits/react-pagination/dist/reactRouterPagination'
112-
```
97+
import { useQueryAndPagination } from '@aboutbits/react-pagination/react-router/zod'
98+
import { z } from 'zod'
99+
100+
const userSchema = z.object({
101+
name: z.string(),
102+
// The input to the parser is going to be a string.
103+
// We try to convert it to a number and default to undefined if the parsing fails.
104+
// This continues the parsing of the remaining query.
105+
// Another possibility would be to not catch errors, which would cancel the entire parsing
106+
// if "age" cannot be converted to a number.
107+
age: z.string().pipe(z.coerce.number().optional()).catch(undefined),
108+
})
113109

114-
### NextJS Router based pagination
115-
116-
These are specific hooks for applications that use [NextJS Router](https://nextjs.org/docs/api-reference/next/router)
117-
for routing.
110+
const users = [
111+
{ name: 'Alex', age: 10 },
112+
{ name: 'Simon', age: 24 },
113+
{ name: 'Natan', age: 88 },
114+
{ name: 'Nadia', age: 42 },
115+
{ name: 'Moritz', age: 35 },
116+
{ name: 'Marie', age: 17 },
117+
]
118118

119-
```tsx
120-
import { useQueryAndPagination } from '@aboutbits/react-pagination/dist/nextRouterPagination'
119+
export function UserList() {
120+
const { page, size, query, setQuery, setPage, resetQuery } =
121+
useQueryAndPagination({ name: '', age: 0 }, userSchema, {
122+
page: 0,
123+
size: 4,
124+
})
125+
126+
return (
127+
<div>
128+
<div>
129+
Name:
130+
<input
131+
value={query.name}
132+
onChange={(event) => setQuery({ name: event.target.value })}
133+
/>
134+
</div>
135+
<div>
136+
Minimum age:
137+
<input
138+
value={query.age}
139+
onChange={(event) => {
140+
const value = event.target.value
141+
const parsed = parseInt(value)
142+
if (!isNaN(parsed)) {
143+
setQuery({ age: parsed })
144+
}
145+
}}
146+
/>
147+
</div>
148+
<button onClick={() => resetQuery()}>Clear Input</button>
149+
<select
150+
value={page}
151+
onChange={(event) => setPage(parseInt(event.target.value))}
152+
>
153+
<option value="0">First Page</option>
154+
<option value="1">Second Page</option>
155+
</select>
156+
<ul>
157+
{users
158+
.filter(
159+
(user) =>
160+
user.name.toLowerCase().startsWith(query.name.toLowerCase()) &&
161+
user.age >= query.age
162+
)
163+
.slice(page * size, (page + 1) * size)
164+
.map((user) => (
165+
<li key={user.name}>{user.name}</li>
166+
))}
167+
</ul>
168+
</div>
169+
)
170+
}
121171
```
122172

123173
## Build & Publish
124174

125175
To publish the package commit all changes and push them to main. Then run one of the following commands locally:
126176

127-
```bash
177+
```sh
128178
npm version patch
129179
npm version minor
130180
npm version major
131181
```
132182

133-
## Information
183+
## About
134184

135-
About Bits is a company based in South Tyrol, Italy. You can find more information about us
185+
AboutBits is a company based in South Tyrol, Italy. You can find more information about us
136186
on [our website](https://aboutbits.it).
137187

138188
### Support

0 commit comments

Comments
 (0)