Pagination
A pagination component with prev/next buttons and dot indicators, configurable page limits, and optional visibility of controls and dots
Installation
npm install --save @godaddy/antaresProps
totalnumber—Total number of items.
activeIndex?number | undefined—The active page index (0-based). When provided, the component is controlled.
defaultActiveIndex?number | undefined0The initial active page index for uncontrolled mode.
limit?number | undefined1Number of items shown per page. Dots are derived from Math.ceil(total / limit).
variant?"dots" | null | undefined'dots'The variant of the pagination.
hideControls?boolean | undefined—Whether to hide the navigation controls.
onChange?((index: number) => void) | undefined—Called when the active page changes.
prevButtonProps?ButtonProps | undefined—Props forwarded to the previous button.
nextButtonProps?ButtonProps | undefined—Props forwarded to the next button.
dotsProps?FlexProps | undefined—Props forwarded to the pagination dots.
prevButtonRef?RefObject<HTMLButtonElement | null> | undefined—Ref for the previous button.
nextButtonRef?RefObject<HTMLButtonElement | null> | undefined—Ref for the next button.
display?"flex" | "inline-flex" | undefined'flex'The display property for the flex container.
direction?"row" | "column" | "row-reverse" | "column-reverse" | undefined'row'The direction in which to layout children.
wrap?"wrap" | "nowrap" | "wrap-reverse" | undefined—Whether to wrap items onto multiple lines.
as?(React.ElementType & "div") | undefined'div'Polymorphic element type.
padding?Spacing | Spacing[] | undefined—Padding on all sides. Accepts single value or array.
inlinePadding?Spacing | Spacing[] | undefined—Padding on inline (horizontal) direction.
inlinePaddingStart?Spacing | undefined—Padding on inline start (left in LTR).
inlinePaddingEnd?Spacing | undefined—Padding on inline end (right in LTR).
blockPadding?Spacing | Spacing[] | undefined—Padding on block (vertical) direction.
blockPaddingStart?Spacing | undefined—Padding on block start (top).
blockPaddingEnd?Spacing | undefined—Padding on block end (bottom).
elevation?"base" | "card" | "raised" | "overlay" | undefined—Elevation levels for visual depth.
rounding?Rounding | undefined—Rounding values for border radius.
alignSelf?"center" | (string & {}) | "auto" | "normal" | "start" | "end" | "flex-start" | "flex-end" | "self-start" | "self-end" | "stretch" | undefined—In Flex/Grid layout. Cross-axis alignment within flex/grid container.
justifySelf?"center" | (string & {}) | "auto" | "normal" | "start" | "end" | "flex-start" | "flex-end" | "self-start" | "self-end" | "stretch" | "left" | "right" | undefined—In Flex/Grid layout. Main-axis alignment within flex/grid container.
order?string | number | undefined—In Flex/Grid layout. Layout order within flex/grid container.
flex?string | number | undefined—In Flex/Grid layout. Flex shorthand for grow, shrink, and basis.
flexGrow?string | number | undefined—In Flex/Grid layout. How much the item will grow relative to siblings.
flexShrink?string | number | undefined—In Flex/Grid layout. How much the item will shrink relative to siblings.
flexBasis?string | undefined—In Flex/Grid layout. Initial main size before growing/shrinking.
gridArea?string | undefined—In Flex/Grid layout. Named grid area for placement.
gridColumnStart?string | undefined—In Flex/Grid layout. Grid column start line.
gridColumnEnd?string | undefined—In Flex/Grid layout. Grid column end line.
gridRowStart?string | undefined—In Flex/Grid layout. Grid row start line.
gridRowEnd?string | undefined—In Flex/Grid layout. Grid row end line.
justifyContent?"center" | (string & {}) | "normal" | "start" | "end" | "stretch" | "space-around" | "space-between" | "space-evenly" | undefined—The distribution of space around children along the main axis in flex or inline axis in grid
alignContent?"center" | (string & {}) | "normal" | "start" | "end" | "stretch" | "space-around" | "space-between" | "space-evenly" | "baseline" | undefined—The distribution of space around children along the cross axis in flex or block axis in grid
justifyItems?"center" | (string & {}) | "normal" | "start" | "end" | "stretch" | "legacy" | undefined—Defines the default justify-self for all children in a grid container.
alignItems?"center" | (string & {}) | "normal" | "start" | "end" | "stretch" | "baseline" | undefined—Sets the align-self property for each child.
gap?Spacing | Spacing[] | undefined—The gap between children.
columnGap?Spacing | undefined—The gap between columns.
rowGap?Spacing | undefined—The gap between rows.
inputMode?"search" | "text" | "none" | "tel" | "url" | "email" | "numeric" | "decimal" | undefined—Hints at the type of data that might be entered by the user while editing the element or its contents
is?string | undefined—Specify that a standard HTML element should behave like a defined custom built-in element
Examples
Basic Usage
The default pagination is uncontrolled. It renders prev/next buttons and one dot per page. The total prop sets the number of items.
import { Flex, Pagination } from '@godaddy/antares';import { useState } from 'react';export function DefaultExample() { const [page, setPage] = useState(0); return ( <Flex direction="column" gap="sm"> <Pagination total={5} onChange={setPage} /> <Flex as="span" justifyContent="center"> Current page: {page} </Flex> </Flex> );}Controlled
Pass activeIndex and onChange to control the active page externally.
import { Flex, Pagination } from '@godaddy/antares';import { useState } from 'react';export function ControlledExample() { const [page, setPage] = useState(2); return ( <Flex direction="column" gap="sm"> <Pagination total={4} activeIndex={page} onChange={setPage} /> <Flex as="span" justifyContent="center"> Current page: {page} </Flex> </Flex> );}Default Active Index
Use defaultActiveIndex to set the starting page in uncontrolled mode.
import { Pagination } from '@godaddy/antares';export function DefaultActiveExample() { return <Pagination total={5} defaultActiveIndex={2} />;}With Limit
Limit the number of items shown per page. When limit is greater than 1, the number of pages (dots) is derived from Math.ceil(total / limit). For example, 10 items with a limit of 3 produces 4 pages (dots).
import { Pagination } from '@godaddy/antares';export function WithLimitExample() { return <Pagination total={10} limit={3} />;}onChange Event
The onChange callback fires with the new page index whenever the user navigates.
import { Flex, Pagination } from '@godaddy/antares';import { useState } from 'react';export function OnChangeExample() { const [onChangeValue, setOnChangeValue] = useState<number | undefined>(undefined); return ( <Flex direction="column" gap="sm"> <Pagination total={3} onChange={setOnChangeValue} /> <Flex as="span" justifyContent="center"> onChange: {onChangeValue ?? 'none'} </Flex> </Flex> );}