Pagination
View in LexiconPagination provides horizontal navigation between chunks(pages) of a dataset.
| install | yarn add @clayui/pagination |
|---|---|
| version | |
| use | import Pagination, {ClayPaginationWithBasicItems} from '@clayui/pagination'; |
Table of Contents
You can use ClayPagination.Ellipsis to display a dropdown with the specified page numbers as the dropdown’s options.
ClayPagination.Item renders a basic Pagination item with content you provide.
Combining these you can reach the following result:
import {Provider} from '@clayui/core'; import Pagination from '@clayui/pagination'; import React from 'react'; export default function App() { return ( <Provider spritemap="/icons.svg"> <div className="p-4"> <Pagination> <Pagination.Item>{1}</Pagination.Item> <Pagination.Ellipsis aria-label="More" title="More" items={[2, 3, 4, 5]} /> <Pagination.Item>{'End'}</Pagination.Item> </Pagination> </div> </Provider> ); }
Numbered Pagination
If you want to have a simple Pagination with integers as Pagination items you can use a simpler variant, PaginationWithBasicItems as you can see below:
import {Provider} from '@clayui/core'; import {ClayPaginationWithBasicItems} from '@clayui/pagination'; import React from 'react'; export default function App() { const [active, setActive] = useState.useState(8); return ( <Provider spritemap="/icons.svg"> <div className="p-4"> <ClayPaginationWithBasicItems active={active} ellipsisBuffer={2} ellipsisProps={{'aria-label': 'More', title: 'More'}} onActiveChange={setActive} totalPages={25} /> </div> </Provider> ); }
Accessibility
ClayPaginationWithBasicItems generates aria-label’s for the previous, next, page, and ellipsis links. Custom labels can be passed to the previous, next, and page links through the ariaLabels attribute. It is useful for providing translated labels for screen readers or custom text more relevant to your app. The component will replace the placeholder {0} with the page number.
Snippet
<ClayPaginationWithBasicItems ariaLabels={{ link: 'Change the page to {0}', next: 'Change the page to {0}', previous: 'Change the page to {0}', }} activePage={8} ellipsisBuffer={2} totalPages={25} />
The aria-label attribute on ClayPaginationWithBasicItems sets the aria-label on the nav element. It defaults to “Pagination”.
Snippet
<ClayPaginationWithBasicItems aria-label="Pagination for 25 pages worth of stuff" activePage={8} ellipsisBuffer={2} totalPages={25} />
The ellipsis aria-label and title are customized through the ellipsisProps attribute. The placeholder text {0} will be replaced with the first page number on the list and {1} will be replaced with the last page number on the list.
Snippet
<ClayPaginationWithBasicItems activePage={8} ellipsisBuffer={2} ellipsisProps={{ 'aria-label': 'Show links to pages {0} through {1}', title: 'Show links to pages {0} through {1}', }} totalPages={25} />
API Reference
ClayPaginationWithBasicItems
React.ForwardRefExoticComponent<Pick<IProps, "ariaLabels" | "className" | "id" | "size" | "spritemap" | "defaultChecked" | "defaultValue" | "suppressContentEditableWarning" | "suppressHydrationWarning" | "accessKey" | "contentEditable" | "contextMenu" | "dir" | "draggable" | "hidden" | "lang" | "placeholder" | "slot" | "spellCheck" | "style" | "tabIndex" | "title" | "radioGroup" | "role" | "about" | "datatype" | "inlist" | "prefix" | "property" | "resource" | "typeof" | "vocab" | "autoCapitalize" | "autoCorrect" | "autoSave" | "color" | "itemProp" | "itemScope" | "itemType" | "itemID" | "itemRef" | "results" | "security" | "unselectable" | "inputMode" | "is" | "aria-activedescendant" | "aria-atomic" | "aria-autocomplete" | "aria-busy" | "aria-checked" | "aria-colcount" | "aria-colindex" | "aria-colspan" | "aria-controls" | "aria-current" | "aria-describedby" | "aria-details" | "aria-disabled" | "aria-dropeffect" | "aria-errormessage" | "aria-expanded" | "aria-flowto" | "aria-grabbed" | "aria-haspopup" | "aria-hidden" | "aria-invalid" | "aria-keyshortcuts" | "aria-label" | "aria-labelledby" | "aria-level" | "aria-live" | "aria-modal" | "aria-multiline" | "aria-multiselectable" | "aria-orientation" | "aria-owns" | "aria-placeholder" | "aria-posinset" | "aria-pressed" | "aria-readonly" | "aria-relevant" | "aria-required" | "aria-roledescription" | "aria-rowcount" | "aria-rowindex" | "aria-rowspan" | "aria-selected" | "aria-setsize" | "aria-sort" | "aria-valuemax" | "aria-valuemin" | "aria-valuenow" | "aria-valuetext" | "children" | "dangerouslySetInnerHTML" | "onCopy" | "onCopyCapture" | "onCut" | "onCutCapture" | "onPaste" | "onPasteCapture" | "onCompositionEnd" | "onCompositionEndCapture" | "onCompositionStart" | "onCompositionStartCapture" | "onCompositionUpdate" | "onCompositionUpdateCapture" | "onFocus" | "onFocusCapture" | "onBlur" | "onBlurCapture" | "onChange" | "onChangeCapture" | "onBeforeInput" | "onBeforeInputCapture" | "onInput" | "onInputCapture" | "onReset" | "onResetCapture" | "onSubmit" | "onSubmitCapture" | "onInvalid" | "onInvalidCapture" | "onLoad" | "onLoadCapture" | "onError" | "onErrorCapture" | "onKeyDown" | "onKeyDownCapture" | "onKeyPress" | "onKeyPressCapture" | "onKeyUp" | "onKeyUpCapture" | "onAbort" | "onAbortCapture" | "onCanPlay" | "onCanPlayCapture" | "onCanPlayThrough" | "onCanPlayThroughCapture" | "onDurationChange" | "onDurationChangeCapture" | "onEmptied" | "onEmptiedCapture" | "onEncrypted" | "onEncryptedCapture" | "onEnded" | "onEndedCapture" | "onLoadedData" | "onLoadedDataCapture" | "onLoadedMetadata" | "onLoadedMetadataCapture" | "onLoadStart" | "onLoadStartCapture" | "onPause" | "onPauseCapture" | "onPlay" | "onPlayCapture" | "onPlaying" | "onPlayingCapture" | "onProgress" | "onProgressCapture" | "onRateChange" | "onRateChangeCapture" | "onSeeked" | "onSeekedCapture" | "onSeeking" | "onSeekingCapture" | "onStalled" | "onStalledCapture" | "onSuspend" | "onSuspendCapture" | "onTimeUpdate" | "onTimeUpdateCapture" | "onVolumeChange" | "onVolumeChangeCapture" | "onWaiting" | "onWaitingCapture" | "onAuxClick" | "onAuxClickCapture" | "onClick" | "onClickCapture" | "onContextMenu" | "onContextMenuCapture" | "onDoubleClick" | "onDoubleClickCapture" | "onDrag" | "onDragCapture" | "onDragEnd" | "onDragEndCapture" | "onDragEnter" | "onDragEnterCapture" | "onDragExit" | "onDragExitCapture" | "onDragLeave" | "onDragLeaveCapture" | "onDragOver" | "onDragOverCapture" | "onDragStart" | "onDragStartCapture" | "onDrop" | "onDropCapture" | "onMouseDown" | "onMouseDownCapture" | "onMouseEnter" | "onMouseLeave" | "onMouseMove" | "onMouseMoveCapture" | "onMouseOut" | "onMouseOutCapture" | "onMouseOver" | "onMouseOverCapture" | "onMouseUp" | "onMouseUpCapture" | "onSelect" | "onSelectCapture" | "onTouchCancel" | "onTouchCancelCapture" | "onTouchEnd" | "onTouchEndCapture" | "onTouchMove" | "onTouchMoveCapture" | "onTouchStart" | "onTouchStartCapture" | "onPointerDown" | "onPointerDownCapture" | "onPointerMove" | "onPointerMoveCapture" | "onPointerUp" | "onPointerUpCapture" | "onPointerCancel" | "onPointerCancelCapture" | "onPointerEnter" | "onPointerEnterCapture" | "onPointerLeave" | "onPointerLeaveCapture" | "onPointerOver" | "onPointerOverCapture" | "onPointerOut" | "onPointerOutCapture" | "onGotPointerCapture" | "onGotPointerCaptureCapture" | "onLostPointerCapture" | "onLostPointerCaptureCapture" | "onScroll" | "onScrollCapture" | "onWheel" | "onWheelCapture" | "onAnimationStart" | "onAnimationStartCapture" | "onAnimationEnd" | "onAnimationEndCapture" | "onAnimationIteration" | "onAnimationIterationCapture" | "onTransitionEnd" | "onTransitionEndCapture" | "key" | "active" | "activePage" | "alignmentPosition" | "defaultActive" | "disabledPages" | "disableEllipsis" | "ellipsisBuffer" | "ellipsisProps" | "hrefConstructor" | "onActiveChange" | "onPageChange" | "totalPages"> & React.RefAttributes<HTMLUListElement>>Parameters
Properties
ariaLabels
{ link: string; previous: string; next: string; } | undefinedLabels for the aria attributes
size
"sm" | "lg" | undefinedThe size of pagination element.
spritemap
string | undefinedPath to spritemap from clay-css.
active
number | undefinedSets the currently active page (controlled).
activePage
number | undefinedThe page that is currently active. The first page is 1.
alignmentPosition
number | AlignPoints | undefinedSets the default DropDown position of the component. The component
receives the Align constant values from the @clayui/drop-down package.
defaultActive
number | undefinedSets the default active page (uncontrolled).
disabledPages
Array<number> | undefinedThe page numbers that should be disabled. For example, [2,5,6].
disableEllipsis
boolean | undefinedFlag to disable ellipsis button
ellipsisBuffer
number | undefinedThe number of pages to show on each side of the active page before using an ellipsis dropdown.
ellipsisProps
{} | undefinedProperties to pass to the ellipsis trigger.
hrefConstructor
((page?: number) => string) | undefinedFunction used to create the href provided for each page link.
onActiveChange
InternalDispatch<number> | undefinedCallback called when the state of the active page changes (controlled). This is only used if an href is not provided.
onPageChange
InternalDispatch<number> | undefinedCallback for when the active page changes. This is only used if an href is not provided.
totalPages *
numberThe total number of pages in the pagination list.
Returns
ReactElement<any, string | JSXElementConstructor<any>> | nullPagination
IForwardRef<HTMLUListElement, IProps>Parameters
Properties
size
"sm" | "lg" | undefinedThe size of pagination element.
Returns
ReactElement<any, string | JSXElementConstructor<any>> | nullItem
({ as: As, active, children, disabled, href, ...otherProps }: IPaginationItemProps) => JSX.ElementParameters
Properties
as
"div" | React.ForwardRefExoticComponent<IProps & React.RefAttributes<HTMLAnchorElement>> | undefined= "ClayLink"active
boolean | undefineddisabled
boolean | undefinedhref
string | undefinedReturns
ElementEllipsis
({ alignmentPosition: _alignmentPosition, disabled, disabledPages, hrefConstructor, items, onPageChange, ...otherProps }: Props) => JSX.ElementParameters
Properties
aria-label
string | undefinedalignmentPosition
number | AlignPoints | undefineddisabled
boolean | undefineddisabledPages
Array<number> | undefined= []hrefConstructor
((page?: number) => string) | undefineditems
Array<number> | undefined= []onPageChange
((page?: number) => void) | undefinedtitle
string | undefinedReturns
ElementContributors
Last edited May 11, 2025 at 5:57:01 PM
Table of Contents