` prop to forward to the root element of the widget.
```jsx JavaScript icon=code theme={"system"}
;
```
## Hook
React InstantSearch let you create your own UI for the `
` widget with `usePagination`.
Hooks provide APIs to access the widget state and interact with InstantSearch.
The `usePagination` Hook accepts [parameters](#parameters) and returns [APIs](#hook).
It must be used inside the [``](/doc/api-reference/widgets/instantsearch/react) component.
### Usage
First, create your React component:
```jsx JavaScript icon=code theme={"system"}
import { usePagination } from "react-instantsearch";
function CustomPagination(props) {
const {
pages,
currentRefinement,
nbHits,
nbPages,
isFirstPage,
isLastPage,
canRefine,
refine,
createURL,
} = usePagination(props);
return <>{/*Your JSX*/};
}
```
Then, render the widget:
```jsx JavaScript icon=code theme={"system"}
```
### Parameters
Hooks accept parameters. You can either pass them manually or forward props from a custom component.
When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders.
Use [`useCallback()`](https://reactjs.org/docs/hooks-reference.html#usecallback) for memoization.
Arrays and objects are automatically memoized.
The maximum number of pages to browse.
```jsx JavaScript icon=code theme={"system"}
const paginationApi = usePagination({
totalPages: 2,
});
```
The number of pages to display on each side of the current page.
```jsx JavaScript icon=code theme={"system"}
const paginationApi = usePagination({
padding: 2,
});
```
### APIs
Hooks return APIs, such as state and functions.
You can use them to build your UI and interact with React InstantSearch.
The list of pages based on the current page and [`padding`](/doc/api-reference/widgets/pagination/react#param-padding).
```jsx JavaScript icon=code theme={"system"}
function Pagination(props) {
const { pages, refine } = usePagination(props);
return (
);
}
```
The current page number.
```jsx JavaScript icon=code theme={"system"}
function Pagination(props) {
const { currentRefinement, pages, refine } = usePagination(props);
return (
);
}
```
The number of hits (can be approximate).
```jsx JavaScript icon=code theme={"system"}
function PageIndicator(props) {
const { currentRefinement, nbPages, nbHits } = usePagination(props);
return (
{currentRefinement + 1} of {nbPages} page(s) for {nbHits} hit(s)
);
}
```
The number of pages for the total result set.
```jsx JavaScript icon=code theme={"system"}
function PageIndicator(props) {
const { currentRefinement, nbPages, nbHits } = usePagination(props);
return (
{currentRefinement + 1} of {nbPages} page(s) for {nbHits} hit(s)
);
}
```
Whether the current page is the first page.
```jsx JavaScript icon=code theme={"system"}
function Pagination(props) {
const { isFirstPage, pages, refine } = usePagination(props);
return (
);
}
```
Whether the current page is the last page.
```jsx JavaScript icon=code theme={"system"}
function Pagination(props) {
const { isLastPage, nbPages, pages, refine } = usePagination(props);
return (
);
}
```
Indicates if the pagination can be refined.
```jsx JavaScript icon=code theme={"system"}
function Pagination(props) {
const { canRefine, pages, refine } = usePagination(props);
if (!canRefine) {
return null;
}
return (
);
}
```
Sets the current page and triggers a search.
```jsx JavaScript icon=code theme={"system"}
function Pagination(props) {
const { pages, refine } = usePagination(props);
return (
);
}
```
Generates a URL of the next search state.
```jsx JavaScript icon=code theme={"system"}
function Pagination(props) {
const { canRefine, pages, refine } = usePagination(props);
return (
);
}
```
### Example
```jsx JavaScript theme={"system"}
import React from "react";
import { usePagination } from "react-instantsearch";
function CustomPagination(props) {
const {
pages,
currentRefinement,
nbPages,
isFirstPage,
isLastPage,
refine,
createURL,
} = usePagination(props);
const firstPageIndex = 0;
const previousPageIndex = currentRefinement - 1;
const nextPageIndex = currentRefinement + 1;
const lastPageIndex = nbPages - 1;
return (
refine(firstPageIndex)}
>
First
refine(previousPageIndex)}
>
Previous
{pages.map((page) => {
const label = page + 1;
return (
refine(page)}
>
{label}
);
})}
refine(nextPageIndex)}
>
Next
refine(lastPageIndex)}
>
Last
);
}
function PaginationItem({ isDisabled, href, onClick, ...props }) {
if (isDisabled) {
return (
);
}
return (
{
if (isModifierClick(event)) {
return;
}
event.preventDefault();
onClick(event);
}}
{...props}
/>
);
}
function isModifierClick(event) {
const isMiddleClick = event.button === 1;
return Boolean(
isMiddleClick ||
event.altKey ||
event.ctrlKey ||
event.metaKey ||
event.shiftKey,
);
}
```
```tsx TypeScript theme={"system"}
import React from "react";
import { usePagination, UsePaginationProps } from "react-instantsearch";
function CustomPagination(props: UsePaginationProps) {
const {
pages,
currentRefinement,
nbPages,
isFirstPage,
isLastPage,
refine,
createURL,
} = usePagination(props);
const firstPageIndex = 0;
const previousPageIndex = currentRefinement - 1;
const nextPageIndex = currentRefinement + 1;
const lastPageIndex = nbPages - 1;
return (
refine(firstPageIndex)}
>
First
refine(previousPageIndex)}
>
Previous
{pages.map((page) => {
const label = page + 1;
return (
refine(page)}
>
{label}
);
})}
refine(nextPageIndex)}
>
Next
refine(lastPageIndex)}
>
Last
);
}
type PaginationItemProps = Omit, "onClick"> & {
onClick: NonNullable["onClick"]>;
isDisabled: boolean;
};
function PaginationItem({
isDisabled,
href,
onClick,
...props
}: PaginationItemProps) {
if (isDisabled) {
return (
);
}
return (
{
if (isModifierClick(event)) {
return;
}
event.preventDefault();
onClick(event);
}}
{...props}
/>
);
}
function isModifierClick(event: React.MouseEvent) {
const isMiddleClick = event.button === 1;
return Boolean(
isMiddleClick ||
event.altKey ||
event.ctrlKey ||
event.metaKey ||
event.shiftKey
);
}
```