Pagination

The Pagination component allows you to display active page and navigate between multiple pages.

Storybook @nextui-org/pagination Source Styles source

Import

NextUI exports 3 pagination-related components:

Pagination: The main component to display a pagination.
PaginationItem: The internal component to display a pagination item.
PaginationCursor: The internal item component to display the current page.

Usage

Disabled

Sizes

Colors

Data Attributes

Pagination has the following attributes on the root element:

data-controls: Indicates whether the pagination has controls. Based on showControls prop.
data-loop: When the pagination is looped. Based on loop prop.
data-dots-jump: Indicates whether the pagination has dots jump. Based on dotsJump prop.
data-total: The total number of pages. Based on total prop.
data-active-page: The active page. Based on activePage prop.

Accessibility

The root node has a role of navigation by default.
The pagination items have an aria-label that identifies the item purpose ("next page button", "previous page button", etc.), you can override this label by using the getItemAriaLabel function.
The pagination items are in tab order, with a tabindex of "0".

API

Pagination Props

Attribute	Type	Description	Default
variant	`flat` \| `bordered` \| `light` \| `faded`	The pagination variant.	`flat`
color	`default` \| `primary` \| `secondary` \| `success` \| `warning` \| `danger`	The pagination color theme.	`default`
size	`sm` \| `md` \| `lg`	The pagination size.	`md`
radius	`none` \| `sm` \| `md` \| `lg` \| `full`	The pagination border radius.	`xl`
total	`number`	The total number of pages.	`1`
dotsJump	`boolean`	The number of pages that are added or subtracted on the '...' button.	`5`
initialPage	`number`	The initial page. (uncontrolled)	`1`
page	`number`	The current page. (controlled)	-
siblings	`number`	The number of pages to show before and after the current page.	`1`
boundaries	`number`	The number of pages to show at the beginning and end of the pagination.	`1`
loop	`boolean`	Whether the pagination should be looped.	`false`
isCompact	`boolean`	Whether the pagination should have a compact style.	`false`
isDisabled	`boolean`	Whether the pagination is disabled.	`false`
showShadow	`boolean`	Whether the pagination cursor should have a shadow.	`false`
showControls	`boolean`	Whether the pagination should have controls.	`false`
disableCursorAnimation	`boolean`	Whether the pagination cursor should be hidden.	`false`
renderItem	PaginationItemProps	The pagination item render function.	-
getItemAriaLabel	`(page: string) => string`	A function that allows you to customize the pagination items aria-label.	-
disableAnimation	`boolean`	Whether the pagination cursor should be animated.	`false`
classNames	`Record<"base"｜ "wrapper" ｜ "prev"｜ "next" ｜ "item" ｜ "cursor" ｜ "forwardIcon" ｜ "ellipsis" ｜ "chevronNext", string>`	Allows to set custom class names for the pagination slots.	-

Pagination Events

Attribute	Type	Description
onChange	`(page: number) => void`	Handler that is called when the pagination acitve page changes.

Types

Pagination Item Props

export type PaginationItemRenderProps = {
  // The pagination item ref.
  ref?: Ref<T>;
  // The pagination item value.
  value: PaginationItemValue;
  // The pagination item index.
  index: number;
  // The active page number.
  activePage: number;
  // Whether the pagination item is active.
  isActive: boolean;
  // Whether the pagination item is the first item in the pagination.
  isFirst: boolean;
  // Whether the pagination item is the last item in the pagination.
  isLast: boolean;
  // Whether the pagination item is the next item in the pagination.
  isNext: boolean;
  // Whether the pagination item is the previous item in the pagination.
  isPrevious: boolean;
  // The pagination item className.
  className: string;
  // Callback to go to the next page.
  onNext: () => void;
  // Callback to go to the previous page.
  onPrevious: () => void;
  // Callback to go to the page.
  setPage: (page: number) => void;
};

type renderItem?: (props: PaginationItemRenderProps) => ReactNode;