Pagination

Importing

import { Pagination } from '@customerio/pluma-components/react';

Usage

To use the component, at a minimum you'll need to pass in the following props:

• page - the current page
  • the component doesn't manage the page state internally - if it changes due to a navigation or callback, make sure to update the property that's passed in
• totalItemCount - the total number of items across all pages
  • this is used to calculate how many pages are available, and how many items there are on the last page
  • if the count is unknown, pass in -1 to have the component say "many" in the page count instead of the actual page count
• onPageChange and/or hrefBuilder
  • onPageChange is called when a page button is clicked, which allows you to update the page state
  • hrefBuilder, if provided, will be used to generate href strings, to be used in the navigation buttons (which will be a tags instead of button tags in this case)

import { Pagination } from '@customerio/pluma-components/react';
import { useState } from 'react';

export default function Example() {
	const [page, setPage] = useState(1);

	return <Pagination
		page={page}
		totalItemCount={83}
		onPageChange={setPage}
	/>
}

Link navigation

For a better navigation experience, it is recommended to use links instead of buttons with callbacks, especially if the page state is reflected as a URL query parameter.

By default, the pagination component will render buttons. However, it accepts a hrefBuilder function for generating links instead.

hrefBuilder will be called with a page number argument, and should return a URL string, or undefined (for example, when the total count of elements is unknown - -1 - it's recommended to return undefined from the hrefBuilder callback).

The links will be rendered using the link component defined on PlumaProvider, if present, so that routing libraries can be used.

<Pagination
	page={3}
	totalItemCount={83}
	hrefBuilder={(page) => '?page=' + page}
/>

Controlling page size

By passing in onPageSizeChange, the component will render a dropdown with options for changing the page size.

The onPageSizeChange callback will be called with the new page size when the user selects a new option. It will show the current page size as the selected option. Additionally, you can pass in a pageSizes prop to customize the options available. By default, the options are [10, 25, 50, 100].

<Pagination
  page={3}
  totalItemCount={83}
  pageSizes={[10, 100, 1000]}
  onPageSizeChange={(newSize) => console.log(newSize)}
/>

currentItemCount

When totalItemCount is unknown (and -1 was passed in), the component won't be able to determine the correct number of items on a page.

By default, the component will use the pageSize and page arguments to calculate how many items fit on a page. However, on a "last page", chances are there will be less items.

To tell the component how many items are actually present on the current page, currentItemCount may be used:

<Pagination
	page={2}
	totalItemCount={-1}
	currentItemCount={20}
/>

<Pagination
	page={3}
	totalItemCount={-1}
	currentItemCount={7}
/>

Note: If currentItemCount is less than the pageSize, the component assumes the current page is the last page (and will disable the "next" and "last" page buttons accordingly).

Continuation-based pagination

This component supports continuation-based pagination, where the current page number is unknown, and it's only possible to page to the first, previous, next, or last page.

For these use cases, the page argument can be omitted. Additionally, the hrefBuilder and onPageChange callbacks include a second argument, indicating which page button was clicked. The value is a string, one of: first, previous, next, or last. These can be used, instead of a page number, to construct the "paged" link URLs, or update state in the callback.

The first argument to these callbacks, page, will be -1 in these cases.

import { Pagination } from '@customerio/pluma-components/react';
import { useState } from 'react';

export default function Example() {
	const hrefBuilder = (page, control) => {
		if (control === 'first') {
			return '?cursor=first';
		} else if (control === 'previous') {
			return '?cursor=foo';
		} else if (control === 'next') {
			return '?cursor=bar';
		} else if (control === 'last') {
			return '?cursor=last';
		}
	}

	return <Pagination
		hrefBuilder={hrefBuilder}
	/>;
}