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; } | undefined
Labels for the aria attributes
size
"sm" | "lg" | undefined
The size of pagination element.
spritemap
string | undefined
Path to spritemap from clay-css.
active
number | undefined
Sets the currently active page (controlled).
activePage
number | undefined
The page that is currently active. The first page is 1
.
alignmentPosition
number | AlignPoints | undefined
Sets the default DropDown position of the component. The component
receives the Align constant values from the @clayui/drop-down
package.
defaultActive
number | undefined
Sets the default active page (uncontrolled).
disabledPages
Array<number> | undefined
The page numbers that should be disabled. For example, [2,5,6]
.
disableEllipsis
boolean | undefined
Flag to disable ellipsis button
ellipsisBuffer
number | undefined
The number of pages to show on each side of the active page before using an ellipsis dropdown.
ellipsisProps
{} | undefined
Properties to pass to the ellipsis trigger.
hrefConstructor
((page?: number) => string) | undefined
Function used to create the href provided for each page link.
onActiveChange
InternalDispatch<number> | undefined
Callback called when the state of the active page changes (controlled). This is only used if an href is not provided.
onPageChange
InternalDispatch<number> | undefined
Callback for when the active page changes. This is only used if an href is not provided.
totalPages *
number
The total number of pages in the pagination list.
Returns
ReactElement<any, string | JSXElementConstructor<any>> | nullPagination
IForwardRef<HTMLUListElement, IProps>
Parameters
Properties
size
"sm" | "lg" | undefined
The size of pagination element.
Returns
ReactElement<any, string | JSXElementConstructor<any>> | nullItem
({ as: As, active, children, disabled, href, ...otherProps }: IPaginationItemProps) => JSX.Element
Parameters
Properties
as
"div" | React.ForwardRefExoticComponent<IProps & React.RefAttributes<HTMLAnchorElement>> | undefined
= "ClayLink"
active
boolean | undefined
disabled
boolean | undefined
href
string | undefined
Returns
ElementEllipsis
({ alignmentPosition: _alignmentPosition, disabled, disabledPages, hrefConstructor, items, onPageChange, ...otherProps }: Props) => JSX.Element
Parameters
Properties
aria-label
string | undefined
alignmentPosition
number | AlignPoints | undefined
disabled
boolean | undefined
disabledPages
Array<number> | undefined
= []
hrefConstructor
((page?: number) => string) | undefined
items
Array<number> | undefined
= []
onPageChange
((page?: number) => void) | undefined
title
string | undefined
Returns
ElementContributors
Last edited May 11, 2025 at 5:57:01 PM
Table of Contents