Pagination

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


Installation

npx nextui-cli@latest add pagination
The above command is for individual installation only. You may skip this step if @nextui-org/react is already installed globally.

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

Variants

You can use the variant property to change the pagination items style.

With Controls

You can set the showControls to true to display the next and previous buttons.

Pagination Loop

In case you want to loop the pagination, you can set the loop property to true. The cursor will go back to the first page when it reaches the last page and vice versa.

Changing the initial page

You can change the initial page by setting the initialPage property.

Compact Pagination

You can set the isCompact property to true to display reduced version of the pagination.

With Shadow

You can use the showShadow property to display a shadow below the active page item.

Controlled

Siblings

You can control the number of pages to show before and after the current page by setting the siblings property.

Boundaries

You can control the number of pages to show at the beginning and end of the pagination by setting the boundaries property.

Custom items

You can use the renderItem property to customize the pagination items.

Slots

  • base: The main pagination slot.
  • wrapper: The pagination wrapper slot. This wraps the pagination items.
  • prev: The previous button slot.
  • next: The next button slot.
  • item: The pagination item slot, applied to the middle items.
  • cursor: The current page slot. Available only when disableCursorAnimation is false and disableAnimation is false.
  • forwardIcon: The forward icon slot. The one that appears when hovering the ellipsis button.
  • ellipsis: The ellipsis slot.
  • chevronNext: The chevron next icon slot.

Custom Styles

You can customize the Pagination component by passing custom Tailwind CSS classes to the component slots.

Custom Implementation

In case you need to customize the pagination even further, you can use the usePagination hook to create your own implementation.

Data Attributes

Pagination has the following attributes on the base 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

AttributeTypeDescriptionDefault
variantflat | bordered | light | fadedThe pagination variant.flat
colordefault | primary | secondary | success | warning | dangerThe pagination color theme.default
sizesm | md | lgThe pagination size.md
radiusnone | sm | md | lg | fullThe pagination border radius.xl
totalnumberThe total number of pages.1
dotsJumpnumberThe number of pages that are added or subtracted on the '...' button.5
initialPagenumberThe initial page. (uncontrolled)1
pagenumberThe current page. (controlled)-
siblingsnumberThe number of pages to show before and after the current page.1
boundariesnumberThe number of pages to show at the beginning and end of the pagination.1
loopbooleanWhether the pagination should be looped.false
isCompactbooleanWhether the pagination should have a compact style.false
isDisabledbooleanWhether the pagination is disabled.false
showShadowbooleanWhether the pagination cursor should have a shadow.false
showControlsbooleanWhether the pagination should have controls.false
disableCursorAnimationbooleanWhether the pagination cursor should be hidden.false
renderItemPaginationItemPropsThe pagination item render function.-
getItemAriaLabel(page: string) => stringA function that allows you to customize the pagination items aria-label.-
disableAnimationbooleanWhether the pagination cursor should be animated.false
classNamesRecord<"base"| "wrapper" | "prev"| "next" | "item" | "cursor" | "forwardIcon" | "ellipsis" | "chevronNext", string>Allows to set custom class names for the pagination slots.-

Pagination Events

AttributeTypeDescription
onChange(page: number) => voidHandler that is called when the pagination active 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;