Pagination

Overview

Pagination is used to divide a long list or table into several pages, indicating other pages exist and allowing the user to access them. This makes the content easier to read and ensures faster loading time. The user can easily navigate through the pages in order, or jump to any page in the list. The user can also select the number of results they want to see on each page, giving them more control over the way they view the data.

When to use:

  • On tables that contain more than 25 number of rows of data/content.

Implementation

Edit the code below to see your changes live!

function ExampleList() {
  const [items] = useState(['Item1', 'Item2', 'Item3', 'Item 4', 'Item 5']);
  const [ranges] = useState([2, 3, 4]);
  const [range, setRange] = useState(ranges[0]);
  const [page, setPage] = useState(1);
  const [currentItems, setCurrentItems] = useState(['']);

  const onItemsPerPageChange = (newRange) => {
    setPage(1);
    setRange(newRange);
  };

  useEffect(() => {
    const maxItems = page * range;
    const lastItem = Math.min(maxItems, items.length);
    const firstItem = Math.max(0, maxItems - range);

    setCurrentItems(items.slice(firstItem, lastItem));
  }, [page, items, range]);

  return (
    <>
      <Pagination
        currentPage={page}
        itemsPerPage={range}
        itemsPerPageOptions={ranges}
        onItemsPerPageChange={onItemsPerPageChange}
        onPageChange={(newPage) => setPage(newPage)}
        totalItems={items.length}
      />
      <ul>
        {currentItems.map((item) => (
          <li key={item}>{item}</li>
        ))}
      </ul>
    </>
  );
}

Props

Prop name
Type
Default
Description
itemsPerPage *number

Indicates how many items are displayed per page.

currentPage *number

Indicates the page currently/initially displayed.

totalItems *number

Indicates how many items in total will be displayed.

itemsPerPageOptions *number[]

Indicates options for per-page ranges.

onPageChange *(page: number) => void

Function that will be called when a navigation arrow is clicked.

onItemsPerPageChange *(range: number) => void

Function that will be called when a new per-page range is selected.

labelstringpagination

Overrides the aria label of the pagination wrapper navigation element.

getRangeLabel(start: number, end: number, totalItems: number) => string

A callback to format the label of the per-page range dropdown.

localization{ of: string, previousPage: string, nextPage: string }

Overrides the labels with localized text.

Props ending with * are required

Inherited

Expand

Margin Props

Do's and Don'ts

Do
Place Pagination directly above the header of the table that it controls, right aligned.
Disable dropdown options greater than the option that will show the total number of results (e.g., if there are 42 results, the highest option should be 50).
Dropdown increments should be multiples of 10 and in increments that make sense for the context.
Don't
Don’t place Pagination below a table.
Don’t show dropdown arrow when there are less than 10 items.