Use Pagination - Mantine

import { PaginationDemos, UsePaginationDemos } from '@docs/demos'; import { Layout } from '@/layout'; import { MDX_DATA } from '@/mdx';

export default Layout(MDX_DATA.usePagination);

Usage

The use-pagination hook is a state management hook for the Pagination component; it manages pagination with controlled and uncontrolled state:

tsx

import { usePagination } from '@mantine/hooks';

const pagination = usePagination({ total: 10, initialPage: 1 });

pagination.range; // -> [1, 2, 3, 4, 5, 'dots', 10];

pagination.setPage(5);
pagination.range; // -> [1, 'dots', 4, 5, 6, 'dots', 10];

pagination.next();
pagination.range; // -> [1, 'dots', 5, 6, 7, 'dots', 10];

pagination.previous();
pagination.range; // -> [1, 'dots', 4, 5, 6, 'dots', 10];

pagination.last();
pagination.range; // -> [1, 'dots', 6, 7, 8, 9, 10];

pagination.first();
pagination.range; // -> [1, 2, 3, 4, 5, 'dots', 10];

Controlled

The hook supports controlled mode; provide page and onChange props to manage state from outside:

tsx

import { useState } from 'react';
import { usePagination } from '@mantine/hooks';

const [page, onChange] = useState(1);
const pagination = usePagination({ total: 10, page, onChange });

// Will call onChange with 5
pagination.setPage(5);
pagination.range; // -> [1, 'dots', 4, 5, 6, 'dots', 10];

// ... All other examples work the same

Siblings

Control number of active item siblings with siblings:

tsx

import { usePagination } from '@mantine/hooks';

const pagination = usePagination({ total: 20, siblings: 3 });

Boundaries

Control number of items on each boundary with boundaries:

tsx

import { usePagination } from '@mantine/hooks';

const pagination = usePagination({ total: 20, boundaries: 3 });

Start value

Set startValue to define the starting page number. For example, with startValue={5} and total={15}, the pagination range will be from 5 to 15:

Definition

tsx

export interface UsePaginationOptions {
  /** Page selected on initial render, defaults to 1 or startValue if provided */
  initialPage?: number;

  /** Controlled active page number */
  page?: number;

  /** Total amount of pages */
  total: number;

  /** Siblings amount on left/right side of selected page, defaults to 1 */
  siblings?: number;

  /** Amount of elements visible on left/right edges, defaults to 1  */
  boundaries?: number;

  /** Callback fired after change of each page */
  onChange?: (page: number) => void;

  /** Starting page number, defaults to 1 */
  startValue?: number;
}

export interface UsePaginationReturnValue {
  /** Array of page numbers and dots */
  range: (number | 'dots')[];

  /** Active page number */
  active: number;

  /** Function to set active page */
  setPage: (page: number) => void;

  /** Function to go to next page */
  next: () => void;

  /** Function to go to previous page */
  previous: () => void;

  /** Function to go to first page */
  first: () => void;

  /** Function to go to last page */
  last: () => void;
}

function usePagination(settings: UsePaginationOptions): UsePaginationReturnValue;

Exported types

UsePaginationOptions and UsePaginationReturnValue types are exported from the @mantine/hooks package; you can import them in your application:

tsx

import type { UsePaginationOptions, UsePaginationReturnValue } from '@mantine/hooks';