@rc-component/pagination

_{Part of the Ant Design ecosystem.}

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

English | 简体中文

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.