Pagination

Components and hooks for navigating through paged data with cursor-based and offset-based pagination strategies.

Cursor Pagination

A pagination component for use with cursor-based pagination. Cursor-based pagination loads data in chunks by using a cursor from the last item on the current page to know where to start the next set. It doesn't let you jump to a specific page or know how many total pages there are, but it's more efficient for large or real-time data sets.

100 per page

1import { CursorPagination } from "@ngrok/mantle/pagination";2 3<CursorPagination.Root defaultPageSize={100}>4	<CursorPagination.PageSizeSelect />5	<CursorPagination.Buttons hasNextPage hasPreviousPage />6</CursorPagination.Root>7 8<CursorPagination.Root defaultPageSize={100}>9	<CursorPagination.PageSizeValue />10	<CursorPagination.Buttons hasNextPage hasPreviousPage />11</CursorPagination.Root>12 13<CursorPagination.Root defaultPageSize={20}>14	<CursorPagination.Buttons hasNextPage hasPreviousPage={false} />15</CursorPagination.Root>

API Reference

CursorPagination.Root

The root container for cursor-based pagination. Manages the page size state.

All props from the HTML div element, plus:

Prop	Type	Default	Description
`defaultPageSize`	`number`		The default number of items per page.

CursorPagination.Buttons

A pair of previous/next buttons for navigating between pages.

Prop	Type	Description
`hasNextPage`	`boolean`	Whether there is a next page of data to load.
`hasPreviousPage`	`boolean`	Whether there is a previous page of data to load.
`onNextPage?`	`() => void`	Callback called when the next page button is clicked.
`onPreviousPage?`	`() => void`	Callback called when the previous page button is clicked.

CursorPagination.PageSizeSelect

A select input for changing the number of items per page.

Prop	Type	Default	Description
`pageSizes?`	`readonly number[]`	`[5, 10, 20, 50, 100]`	A list of page sizes to choose from.
`onChangePageSize?`	`(value: number) => void`		Callback called when the page size is changed.

CursorPagination.PageSizeValue

Displays the current page size as a read-only value (e.g. "100 per page").

Prop	Type	Default	Description
`asChild?`	`boolean`	`false`	Compose onto an alternative element type or your own React component.

Offset Pagination

useOffsetPagination

A headless hook for managing offset-based pagination state. Offset-based pagination lets you jump to a specific page and know the total number of pages.

1import { useOffsetPagination } from "@ngrok/mantle/pagination";2 3const pagination = useOffsetPagination({4	listSize: 150,5	pageSize: 10,6});7 8// pagination.currentPage — current page number (1-indexed)9// pagination.totalPages — total number of pages10// pagination.hasNextPage — whether there is a next page11// pagination.hasPreviousPage — whether there is a previous page12// pagination.nextPage() — go to next page13// pagination.previousPage() — go to previous page14// pagination.goToPage(n) — go to a specific page15// pagination.goToFirstPage() — go to the first page16// pagination.goToLastPage() — go to the last page17// pagination.offset — the offset of the current page18// pagination.pageSize — the current page size19// pagination.setPageSize(n) — set the page size (resets to page 1)

Parameter	Type	Description
`listSize`	`number`	The total number of items in the list.
`pageSize`	`number`	The number of items per page.

getOffsetPaginatedSlice

A utility function to get a paginated slice of a list based on the current offset pagination state.

1import { getOffsetPaginatedSlice, useOffsetPagination } from "@ngrok/mantle/pagination";2 3const data = ["a", "b", "c", "d", "e", "f"];4const pagination = useOffsetPagination({ listSize: data.length, pageSize: 2 });5const currentPageData = getOffsetPaginatedSlice(data, pagination);6// Returns: ['a', 'b'] for page 1, ['c', 'd'] for page 2, etc.