react-component/pagination

README

@rc-component/pagination

_{Part of the Ant Design ecosystem.}

📄 React pagination primitives for page navigation, size changing, quick jumping, and locale-aware controls.

Highlights

Controlled and uncontrolled pagination state.
Page-size changer, quick jumper, simple mode, compact item count, and custom item rendering.
Locale packages exposed from @rc-component/pagination/locale/*.
Semantic classNames and styles for item-level customization.
TypeScript definitions for props, locale, callbacks, and state.
Used by Ant Design as the shared pagination foundation.

Install

npm install @rc-component/pagination

Usage

import Pagination from '@rc-component/pagination';
import '@rc-component/pagination/assets/index.css';
export default () => (
  <Pagination defaultCurrent={1} total={120} showSizeChanger showQuickJumper />
);

import Pagination from '@rc-component/pagination';
import enUS from '@rc-component/pagination/locale/en_US';
export default () => (
  <Pagination
    defaultCurrent={2}
    total={500}
    locale={enUS}
    showTotal={(total, range) => `${range[0]}-${range[1]} of ${total} items`}
  />
);

Examples

Run the local dumi site:

npm install
npm start

Then open http://localhost:8000.

API

Pagination

Property	Type	Default	Description
align	`'start' \| 'center' \| 'end'`	-	Align pagination items.
className	`string`	-	Class name for the root element.
classNames	`Partial<Record<'item', string>>`	-	Semantic class names.
current	`number`	-	Controlled current page.
defaultCurrent	`number`	`1`	Initial current page.
defaultPageSize	`number`	`10`	Initial page size.
disabled	`boolean`	`false`	Disable pagination interactions.
hideOnSinglePage	`boolean`	`false`	Hide when there is only one page.
itemRender	`(page, type, element) => ReactNode`	-	Customize page, previous, next, and jump items.
jumpNextIcon	`ReactNode \| ComponentType`	-	Custom next-jump icon.
jumpPrevIcon	`ReactNode \| ComponentType`	-	Custom previous-jump icon.
locale	`PaginationLocale`	`zh_CN`	Locale text.
nextIcon	`ReactNode \| ComponentType`	-	Custom next icon.
pageSize	`number`	-	Controlled page size.
pageSizeOptions	`number[]`	-	Page-size options.
prefixCls	`string`	`rc-pagination`	Class name prefix.
prevIcon	`ReactNode \| ComponentType`	-	Custom previous icon.
role	`React.AriaRole`	-	WAI-ARIA role.
selectPrefixCls	`string`	`rc-select`	Prefix for the size changer select.
showLessItems	`boolean`	`false`	Show fewer page items.
showPrevNextJumpers	`boolean`	`true`	Show previous and next jumpers.
showQuickJumper	`boolean \| object`	`false`	Show quick page jumper.
showSizeChanger	`boolean`	`total > totalBoundaryShowSizeChanger`	Show page-size changer.
showTitle	`boolean`	`true`	Show title on page items.
showTotal	`(total, range) => ReactNode`	-	Render total text.
simple	`boolean \| { readOnly?: boolean }`	`false`	Use simple pager.
sizeChangerRender	`SizeChangerRender`	-	Customize the size changer.
style	`React.CSSProperties`	-	Root inline style.
styles	`Partial<Record<'item', CSSProperties>>`	-	Semantic styles.
total	`number`	`0`	Total item count.
totalBoundaryShowSizeChanger	`number`	`50`	Boundary for default `showSizeChanger`.
onChange	`(page: number, pageSize: number, info?: { recommendPage?: number }) => void`	-	Triggered when page or page size changes. The `info.recommendPage` is only provided when pageSize changes, indicating the recommended page number based on the new page size.
onShowSizeChange	`(current: number, size: number) => void`	-	Triggered when page size changes.

Custom item accessibility

Default page and jump anchors expose button semantics, and previous/next actions use native buttons. The outer li keeps its list-item semantics. Focus, labels, current-page state, and activation belong to the inner control.

When itemRender or an icon supplies a DOM element, Pagination merges its control semantics (role, labels, tab order, and activation) directly onto that element instead of wrapping it. Native buttons and links with href keep their own keyboard activation; other DOM elements receive button semantics and Enter/Space handling. Native buttons preserve their disabled state and default to type="button" unless a type is explicitly supplied.

Custom components, Fragments, and plain content retain delegated interaction on the list item, since custom components need not forward DOM props. Custom previous/next components continue to receive the disabled input. Authors are responsible for accessible control semantics inside these custom renderers; Pagination does not introduce an interactive wrapper around them.

Custom styles that target the outer item's focus should also account for focus on its child, for example with :focus-within or a child :focus-visible rule.

Development

npm install
npm start
npm test
npm run tsc
npm run coverage
npm run compile
npm run build

The dumi site runs at http://localhost:8000 by default.

Release

npm run prepublishOnly

The release flow is handled by @rc-component/np through the rc-np command after the package build.

License

@rc-component/pagination is released under the MIT license.