---
title: Pagination
description: Pagination with page navigation, next and previous links.
icon: chevron-right
author:
  name: shadcn
  url: https://github.com/shadcn
mode: wide
---

<PoweredBy
  packages={[
    { name: 'Shadcn UI', url: 'https://ui.shadcn.com/docs/components/pagination' },
    { name: 'Lucide', url: 'https://lucide.dev/' },
  ]}
/>

### Installation

```package-install
npx shadcn@latest add @redpanda/pagination
```

<ComponentPreview name="pagination-demo" />

## When to use

Pagination components help users navigate through large datasets by breaking content into manageable pages. Use this decision tree to determine when it's appropriate:

```mermaid
graph TD;
    A[❓ Large dataset to display?] --> B{More than one page needed?};
    A --> C[ℹ️ Show all content];
    B --> D{Simple prev/next sufficient?};
    B --> E{Need page numbers?};
    D --> F[✅ Use SimplePagination];
    E --> G[✅ Use full Pagination];
    E --> H{"Many pages (20+)?"};
    H --> I[✅ Use Pagination with ellipsis];
    H --> J[✅ Use standard Pagination];

    classDef recommended fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#000;
    classDef discouraged fill:#fbbf24,stroke:#f59e0b,stroke-width:2px,color:#000;
    classDef decision fill:#60a5fa,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef neutral fill:#9ca3af,stroke:#6b7280,stroke-width:2px,color:#fff;

    class F,G,I,J recommended;
    class A,B,D,E,H decision;
    class C neutral;
```

## Usage

```tsx
import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
  SimplePagination,
} from '@/components/ui/pagination';
```

```tsx
<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious href="#" />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="#">1</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationEllipsis />
    </PaginationItem>
    <PaginationItem>
      <PaginationNext href="#" />
    </PaginationItem>
  </PaginationContent>
</Pagination>
```

### Examples

## Default

<ComponentPreview name="pagination-demo" />

## Card

<ComponentPreview name="pagination-card-demo" />

## Simple Pagination

A higher-level component that provides smart pagination with ellipsis handling.

<ComponentPreview name="pagination-simple-demo" />

### SimplePagination Props

| Prop              | Type                     | Default | Description                            |
| ----------------- | ------------------------ | ------- | -------------------------------------- |
| `currentPage`     | `number`                 | -       | The current active page (required)     |
| `totalPages`      | `number`                 | -       | Total number of pages (required)       |
| `onPageChange`    | `(page: number) => void` | -       | Callback when page changes             |
| `showEllipsis`    | `boolean`                | `true`  | Whether to show ellipsis (...)         |
| `maxVisiblePages` | `number`                 | `5`     | Maximum number of page buttons to show |
| `className`       | `string`                 | -       | Additional CSS classes                 |

### Usage

```tsx
import { SimplePagination } from '@/components/ui/pagination';

function MyComponent() {
  const [currentPage, setCurrentPage] = useState(1);
  const totalPages = 20;

  return <SimplePagination currentPage={currentPage} totalPages={totalPages} onPageChange={setCurrentPage} />;
}
```

### Next.js

By default the `<PaginationLink />` component will render an `<a />` tag.

To use the Next.js `<Link />` component, make the following updates to `pagination.tsx`.

```diff lineNumbers {1}
+ import Link from "next/link"

- type PaginationLinkProps = ... & React.ComponentProps<"a">
+ type PaginationLinkProps = ... & React.ComponentProps<typeof Link>

const PaginationLink = ({...props }: ) => (
  <PaginationItem>
-   <a>
+   <Link>
      // ...
-   </a>
+   </Link>
  </PaginationItem>
)

```

:::info
**Note:** Shadcn CLI is expecting updates to automatically do this for us.
:::

## Credits

- We take our inspiration from [Shadcn UI](https://ui.shadcn.com/docs/components/pagination) for the pagination component and style.