Pagination

The <Pagination /> component is used to split up a large data set into several pages. It allows users to navigate these pages and set how many items they want to view per page.

Show codeCopy code

The Pagination component is designed to be used as a controlled component, that notifies you of valid page changes with the onPageUpdate callback.

This saves you from having to implement:

• Handlers for all four buttons.
• Handlers for the items per page select-list.
• Calculating the page changes when the user changes the items per page.
• Keeping the user on the page with the same data when they change items per page.
• Ensuring a valid page is always displayed.

Use the two inputs below to mimic your currentPage and currentItemsPerPage from your parent component's state. Notice how setting an invalid currentPage (e.g. 1000) still displays a valid page in the Pagination component.

Show codeCopy code

There are two key parts to integrating the Pagination component and accessing its state: the first part is pagination state which is available to the parent by passing a function to the second part, onPageUpdate.

The pagination state object is the first parameter of the onPageUpdate callback and takes the following shape:

type PaginationState = {
  currentPage: number;
  currentItemsPerPage: ItemsPerPageOption; // a number in the `itemsPerPageOptions` array
  prevPage: number | null;
  nextPage: number | null;
  rangeStart: number;
  rangeEnd: number;
};

By passing in a callback for onPageUpdate you can access the current state of the Pagination component and react accordingly. e.g. when a new currentPage value is set you can fetch the new data or pre-fetch data for the prevPage and nextPage, if that's desirable. onPageUpdate will run everytime the user changes the state of the Pagination component or when currentPage or currentItemsPerPage props are updated. Most importantly, it will always give you valid values for these two props.

Watch "Current pagination state" change as you interact with the component below, e.g. press "Next page" or change the "Items per page".

Show codeCopy code

A TypeScript example of the onPageUpdate function used to fetch data and update local state could be:

const [currentPage, setCurrentPage] = useState(1);
const [currentItemsPerPage, setCurrentItemsPerPage] = useState(10);
const [tableData, setTableData] = useState({});

useEffect(() => {
  // Define yor API search parameters with valid data from the Pagination component
  const searchParams = new URLSearchParams({
    page: `${currentPage}`,
    itemsPerPage: `${currentItemsPerPage}`,
  });

  // Perform the API request using the above search parameters
  fetch(`/my-api?${searchParams}`)
    .then((res) => res.json())
    .then(setTableData);
}, [currentPage, currentItemsPerPage]);

const onPageUpdate = (
  paginationState: PaginationState,
  prevPaginationState: PaginationState,
  paginationStateDiff: Partial<PaginationState>
) => {
  // Take a look in the console to see each of these values update
  console.info({ paginationState, prevPaginationState, paginationStateDiff });

  const { currentPage, currentItemsPerPage } = paginationState;
  // Always set these values in your local state as they will have been checked for validity - e.g. the currentPage can't be 10 when there are only two pages
  setCurrentPage(currentPage);
  setCurrentItemsPerPage(currentItemsPerPage);
};

return (
  <Pagination
    currentPage={currentPage}
    currentItemsPerPage={currentItemsPerPage}
    itemsCount={100}
    onPageUpdate={onPageUpdate}
  />
);

The user may select, from a menu, the number of items they wish to be displayed per page. The default options are 10, 20, 30, 40, 50, and 100. The default values can be set by passing a value to the useState function for each of currentPage and currentItemsPerPage. If an invalid value is defined, the Pagination component will find a valid value and return it via the onPageUpdate function.

Show codeCopy code

There are four buttons for navigation, displayed from left to right with the following aria-labels:

• First page
• Previous page
• Next page
• Last page

When a user is on:

• The first page: the First page and Previous page buttons will be disabled.
• The last page: the Next page and Last page buttons will be disabled.

When the smallest number of items to display is equal to or less than the smallest option for items per page, then:

• The controls will be hidden.
• The pagination content will be centred.

Show codeCopy code

By default, elements in the list (e.g. rows in a table) are referred to with the term "Items", and used in "Items per page" and "1 - 10 of 100 items". This can be customised by setting values for both itemsLabelPlural and itemsLabelSingular. The singular version is used when there is only one item to show.

Show codeCopy code

There are two pagination sizes, small and medium (default). The spacing will change depending on the size selected.

Show codeCopy code

Use the block prop to make the pagination fill its container's width.

Note: The block prop splits the items per page elements from navigation elements to opposite sides of the container.

Show codeCopy code

If the option of items per page is set to a single number, the select will be hidden from view.

Show codeCopy code