Pagination

Move between pages of a larger collection.

View component source ↗

Preview

Example

A minimal example to get started.

Installation

Install this component and its dependencies in a project initialized with shadcn.

pnpm dlx shadcn@latest add https://ui.hyunjoon.net/r/pagination.json

Usage

This is the basic example. Use the Code tab above for the selected example. Adjust import aliases to match your project.

import { useState } from "react";

import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationPrevious,
  PaginationNext,
} from "@/components/ui/pagination";

export default function Example() {
  const [page, setPage] = useState(1);
  return (
    <Pagination>
      <PaginationContent>
        <PaginationItem>
          <PaginationPrevious
            href="#preview"
            aria-disabled={page === 1}
            onClick={(event) => {
              event.preventDefault();
              setPage((current) => Math.max(1, current - 1));
            }}
          />
        </PaginationItem>
        {[1, 2, 3].map((number) => (
          <PaginationItem key={number}>
            <PaginationLink
              href="#preview"
              isActive={page === number}
              onClick={(event) => {
                event.preventDefault();
                setPage(number);
              }}
            >
              {number}
            </PaginationLink>
          </PaginationItem>
        ))}
        <PaginationItem>
          <PaginationNext
            href="#preview"
            aria-disabled={page === 3}
            onClick={(event) => {
              event.preventDefault();
              setPage((current) => Math.min(3, current + 1));
            }}
          />
        </PaginationItem>
      </PaginationContent>
    </Pagination>
  );
}

API reference

Derived from the installed component types. Native DOM props are also supported where applicable. A dash means no explicit default is documented. Some props depend on the selected mode.

Pagination

Pagination properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLElement> \| undefined React.Ref<HTMLElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLElement> \| undefined React.FocusEventHandler<HTMLElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLElement> \| undefined React.FocusEventHandler<HTMLElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLElement, Element> \| undefined React.ChangeEventHandler<HTMLElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLElement> \| undefined React.KeyboardEventHandler<HTMLElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLElement> \| undefined React.MouseEventHandler<HTMLElement> \| undefined	`—`	Called when the element is activated.

PaginationContent

PaginationContent properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLUListElement> \| undefined React.Ref<HTMLUListElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLUListElement> \| undefined React.FocusEventHandler<HTMLUListElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLUListElement> \| undefined React.FocusEventHandler<HTMLUListElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLUListElement, Element> \| undefined React.ChangeEventHandler<HTMLUListElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLUListElement> \| undefined React.KeyboardEventHandler<HTMLUListElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLUListElement> \| undefined React.MouseEventHandler<HTMLUListElement> \| undefined	`—`	Called when the element is activated.

PaginationEllipsis

PaginationEllipsis properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLSpanElement> \| undefined React.Ref<HTMLSpanElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLSpanElement> \| undefined React.FocusEventHandler<HTMLSpanElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLSpanElement> \| undefined React.FocusEventHandler<HTMLSpanElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLSpanElement, Element> \| undefined React.ChangeEventHandler<HTMLSpanElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLSpanElement> \| undefined React.KeyboardEventHandler<HTMLSpanElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLSpanElement> \| undefined React.MouseEventHandler<HTMLSpanElement> \| undefined	`—`	Called when the element is activated.

PaginationItem

PaginationItem properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLLIElement> \| undefined React.Ref<HTMLLIElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`value`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	The current value when controlled by the application.
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLLIElement> \| undefined React.FocusEventHandler<HTMLLIElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLLIElement> \| undefined React.FocusEventHandler<HTMLLIElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLLIElement, Element> \| undefined React.ChangeEventHandler<HTMLLIElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLLIElement> \| undefined React.KeyboardEventHandler<HTMLLIElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLLIElement> \| undefined React.MouseEventHandler<HTMLLIElement> \| undefined	`—`	Called when the element is activated.

PaginationLink

PaginationLink properties
Prop	Type	Default	Description
`isActive`	boolean \| undefined boolean \| undefined	`—`	Marks this item as the current page or selection.
`size`	"default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg" \| null \| undef… "default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg" \| null \| undefined	`"icon"`	Visual size of the component.
`ref`	React.Ref<HTMLAnchorElement> \| undefined React.Ref<HTMLAnchorElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`href`	string \| undefined string \| undefined	`—`	Destination URL for the link.
`target`	React.HTMLAttributeAnchorTarget \| undefined React.HTMLAttributeAnchorTarget \| undefined	`—`	Browsing context in which the link opens.
`type`	string \| undefined string \| undefined	`—`	The native input or button behavior.
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLAnchorElement> \| undefined React.FocusEventHandler<HTMLAnchorElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLAnchorElement> \| undefined React.FocusEventHandler<HTMLAnchorElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLAnchorElement, Element> \| undefined React.ChangeEventHandler<HTMLAnchorElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLAnchorElement> \| undefined React.KeyboardEventHandler<HTMLAnchorElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLAnchorElement> \| undefined React.MouseEventHandler<HTMLAnchorElement> \| undefined	`—`	Called when the element is activated.

PaginationNext

PaginationNext properties
Prop	Type	Default	Description
`isActive`	boolean \| undefined boolean \| undefined	`—`	Marks this item as the current page or selection.
`size`	"default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg" \| null \| undef… "default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg" \| null \| undefined	`—`	Visual size of the component.
`ref`	React.Ref<HTMLAnchorElement> \| undefined React.Ref<HTMLAnchorElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`href`	string \| undefined string \| undefined	`—`	Destination URL for the link.
`target`	React.HTMLAttributeAnchorTarget \| undefined React.HTMLAttributeAnchorTarget \| undefined	`—`	Browsing context in which the link opens.
`type`	string \| undefined string \| undefined	`—`	The native input or button behavior.
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLAnchorElement> \| undefined React.FocusEventHandler<HTMLAnchorElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLAnchorElement> \| undefined React.FocusEventHandler<HTMLAnchorElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLAnchorElement, Element> \| undefined React.ChangeEventHandler<HTMLAnchorElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLAnchorElement> \| undefined React.KeyboardEventHandler<HTMLAnchorElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLAnchorElement> \| undefined React.MouseEventHandler<HTMLAnchorElement> \| undefined	`—`	Called when the element is activated.
`text`	string \| undefined string \| undefined	`"Next"`	Text displayed by the component.

PaginationPrevious

PaginationPrevious properties
Prop	Type	Default	Description
`isActive`	boolean \| undefined boolean \| undefined	`—`	Marks this item as the current page or selection.
`size`	"default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg" \| null \| undef… "default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg" \| null \| undefined	`—`	Visual size of the component.
`ref`	React.Ref<HTMLAnchorElement> \| undefined React.Ref<HTMLAnchorElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`href`	string \| undefined string \| undefined	`—`	Destination URL for the link.
`target`	React.HTMLAttributeAnchorTarget \| undefined React.HTMLAttributeAnchorTarget \| undefined	`—`	Browsing context in which the link opens.
`type`	string \| undefined string \| undefined	`—`	The native input or button behavior.
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLAnchorElement> \| undefined React.FocusEventHandler<HTMLAnchorElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLAnchorElement> \| undefined React.FocusEventHandler<HTMLAnchorElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLAnchorElement, Element> \| undefined React.ChangeEventHandler<HTMLAnchorElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLAnchorElement> \| undefined React.KeyboardEventHandler<HTMLAnchorElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLAnchorElement> \| undefined React.MouseEventHandler<HTMLAnchorElement> \| undefined	`—`	Called when the element is activated.
`text`	string \| undefined string \| undefined	`"Previous"`	Text displayed by the component.

Usage notes

Track the current page and mark its link active. Connect previous and next actions to your data source or route.