Pagination

Overview

The Pagination component allows navigation through pages of content, with “Previous” and “Next” buttons and — in determinate mode — a page-size selector.

There are two modes:

• Determinate — pass totalItems and pageSize so the component knows how many pages exist.
• Indeterminate — pass indeterminate with hasNext / hasPrevious when the total isn’t known ahead of time; only the Next / Previous controls render.

Variations

Determinate pagination with links

Determinate pagination with page size select

Determinate pagination with custom page size values

The default page-size options are [10, 25, 50].

Indeterminate pagination with links

Indeterminate pagination with callbacks

Indeterminate pagination with callbacks and page select

Installation

Determinate pagination

import { Pagination } from '@harnessio/ui/components'

//...

const [currentPage, setCurrentPage] = useState(1)

return (
  <Pagination
    totalItems={100}
    pageSize={10}
    currentPage={currentPage}
    goToPage={setCurrentPage}
  />
)

Indeterminate pagination

import { Pagination } from '@harnessio/ui/components'

//...

const [currentPage, setCurrentPage] = useState(1)

return (
  <Pagination
    indeterminate
    hasPrevious={currentPage > 1}
    hasNext={currentPage < 100}
    currentPage={currentPage}

    // if need to use links
    getPrevPageLink={() => currentPage - 1}
    getNextPageLink={() => currentPage + 1}

    // if need to use buttons
    onPrevious={() => setCurrentPage(currentPage - 1)}
    onNext={() => setCurrentPage(currentPage + 1)}
  />
)

Usage

Anatomy

Pagination renders a Previous control, a Next control, and — in determinate mode when onPageSizeChange is supplied — an “items per page” select.

• Mode — pass totalItems + pageSize for determinate paging, or indeterminate with hasNext / hasPrevious when the total is unknown.
• Navigation — for each direction choose either a callback (goToPage, or onPrevious / onNext) or a link getter (getPageLink, or getPrevPageLink / getNextPageLink). The two styles are mutually exclusive; callbacks render <button>s, link getters render anchors styled as buttons.
• Page size — providing onPageSizeChange shows the select; pageSizeOptions customizes its choices (default [10, 25, 50]).

<Pagination
  totalItems={100}
  pageSize={pageSize}
  currentPage={currentPage}
  goToPage={setCurrentPage}
  onPageSizeChange={setPageSize}
/>

Best practices

Do

• Use determinate pagination whenever you know the total count — it lets people see how far they can go and pick a page size.
• Use indeterminate pagination for cursor-based or streaming data where the total isn’t available.
• Keep pageSizeOptions short and sensible for the data density of the view.

Don’t

• Don’t mix a callback and a link getter for the same direction — pick one navigation style.
• Don’t use pagination for very small lists that fit on a single page; hide it when there’s only one page of results.

Accessibility

Keyboard

• The Previous / Next controls are standard buttons or links, so they’re reachable and activatable with the keyboard in the usual way.

Labeling

• The Previous and Next controls carry translated aria-labels (“Go to previous page” / “Go to next page”) so their purpose is announced even though they’re icon-only.

Known limitations

• No landmark or page-number list in the shipping component. Pagination renders the Previous / Next controls (and optional page-size select) but does not wrap them in a <nav> and does not render a numbered page list — so there is no aria-current page indicator. If you need a labelled pagination landmark, provide it in the surrounding markup.

Properties

Properties

Base props

Common to both modes.

Prop	Required	Default	Type
className	false		string
onPageSizeChange	false		(size: number) => void
pageSizeOptions	false	[10, 25, 50]	number[]

Determinate mode

Prop	Required	Default	Type
totalItems	true		number
pageSize	true		number
currentPage	true		number
goToPage	false		(page: number) => void
getPageLink	false		(page: number) => string

Indeterminate mode

Prop	Required	Default	Type
indeterminate	true		true
hasPrevious	false		boolean
hasNext	false		boolean
onPrevious	false		() => void
onNext	false		() => void
getPrevPageLink	false		() => string
getNextPageLink	false		() => string