Components

Pagination

Page or cursor navigation under tables and lists, with a page size choice.

Storybook: Storybook
Source: Source

Installation

Package: @bigbang/ui
Import: import { Pagination } from '@bigbang/ui';
Source: Pagination.tsx
Storybook: Pagination · Playground

Pagination is in the @bigbang/ui package. Installation and style files are the same as for Button; see the Button code tab.

import { Pagination } from '@bigbang/ui';

<Pagination page={page} pageCount={20} onPageChange={setPage} />;

The part prop types are exported too: PaginationListProps, PaginationPageProps.

Props

pageSize

Description: Rows per page. Needed for the range in the summary and for the page size select.
Type: number

pageSizeOptions

Description: Sizes offered in the page size select. The select shows only with onPageSizeChange and pageSize.
Type: readonly number[]

onPageSizeChange

Description: Called with the chosen size. Reset the page to 1 there; the old page may no longer exist.
Type: (pageSize: number) => void

totalCount

Description: Total number of rows. Shows the summary: the range ("1-20 / 345") with pageSize, "Total 345" without it or in cursor mode.
Type: number

siblingCount

Description: Page numbers shown on each side of the current page.
Type: number
Default: 1

boundaryCount

Description: Page numbers always shown at the start and the end.
Type: number
Default: 1

disabled

Description: Turns every control inactive, for example while the next page loads. Controls stay focusable (aria-disabled), so focus is not lost.
Type: boolean
Default: false

label

Description: The accessible name of the navigation landmark. Defaults to the library string ui.pagination.label ("Sayfalama" or "Pagination"). Name it when a page has more than one.
Type: string

getPageHref

Description: Makes page controls links for URL-driven pages: it returns the address of a page. Unsafe schemes are dropped. onPageChange is still called on click. Page mode only.
Type: (page: number) => string

size

Description: Item height: 32 or 36 px. Use sm under dense tables.
Type: Size
Default: 'md'

className

Description: For layout only: margins and placement.
Type: string

children

Description: A custom layout from the parts. When set, it replaces the default layout. Put previous, pages and next inside Pagination.List.
Type: ReactNode

mode

Description: Which kind of navigation: numbered page (default), or cursor for previous and next only.
Type: 'page' | 'cursor'
Default: 'page'

pageRequired

Description: The current page, starting at 1.
Type: number

pageCountRequired

Description: The number of pages.
Type: number

onPageChangeRequired

Description: Called with the new page number.
Type: (page: number) => void

hasPreviousRequired

Description: Whether an earlier page exists. Without it the previous control is inactive.
Type: boolean

hasNextRequired

Description: Whether a later page exists. Without it the next control is inactive.
Type: boolean

onPreviousRequired

Description: Called when the user goes to the previous page.
Type: () => void

onNextRequired

Description: Called when the user goes to the next page.
Type: () => void

mode selects one of two forms. In page mode (no mode, or 'page') page, pageCount and onPageChange are required. In cursor mode (mode="cursor") hasPrevious, hasNext, onPrevious and onNext are required; getPageHref works in page mode only.

Parts

Do not use parts when the default layout is enough. For a custom layout pass children; they replace the default layout. Previous, pages and next sit inside Pagination.List.

Part	Element	Props
`Pagination.List`	`<ul>`	Native attributes.
`Pagination.Previous`	A button or link in an `<li>`	None; it takes its state from the root.
`Pagination.Next`	A button or link in an `<li>`	None; it takes its state from the root.
`Pagination.Page`	A button or link in an `<li>`	`page`: the page this control opens.
`Pagination.Ellipsis`	`<li>`	None. `aria-hidden`.
`Pagination.PageSize`	A Select in a `<div>`	None; hidden without `pageSize`, `pageSizeOptions` and `onPageSizeChange`.
`Pagination.Summary`	`<p>`	None; hidden without `totalCount`.

Data attributes

data-component="pagination", data-size, data-mode: on the root.
data-part: list, previous, next, page, ellipsis, page-size, summary, page-of, text.

Page range

paginationRange gives the same algorithm as a pure function; use it when you write a custom display.

import { paginationRange } from '@bigbang/ui';

paginationRange(10, 20); // [1, 'ellipsis-start', 9, 10, 11, 'ellipsis-end', 20]
paginationRange(1, 20, 2, 1); // [1, 2, 3, 4, 5, 6, 7, 'ellipsis-end', 20]