Skip to main content

Starwind UI v3.0 is now available! Migration guide

On this page

Pagination

View Markdown

Installation

Usage

---
import {
  Pagination,
  PaginationEllipsis,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@/components/starwind/pagination";
---
<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious href="#">Prev</PaginationPrevious>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="#">1</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="#" isActive>2</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="#">3</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationEllipsis />
    </PaginationItem>
    <PaginationItem>
      <PaginationNext href="#">Next</PaginationNext>
    </PaginationItem>
  </PaginationContent>
</Pagination>

Composition

Place each control inside a PaginationItem:

Pagination
└── PaginationContent
    ├── PaginationItem
    │   └── PaginationPrevious
    ├── PaginationItem
    │   └── PaginationLink
    ├── PaginationItem
    │   └── PaginationEllipsis
    └── PaginationItem
        └── PaginationNext

Active Page

The basic pagination component includes previous/next buttons and numbered pages.

Tip

Use the isActive prop on <PaginationLink> to highlight the current page.

Sizes

PaginationLink, PaginationPrevious, and PaginationNext accept the Button component’s size values. PaginationLink defaults to size="icon". PaginationPrevious and PaginationNext default to size="md" so their text labels receive standard button spacing. PaginationEllipsis accepts the icon size values and defaults to size="icon".

Use icon-sm, icon, or icon-lg for page links and ellipses. Use sm, md, or lg for previous and next controls. Button supplies the spacing, text size, and icon size for each control.

Size migration

BeforeAfter
<Pagination size="sm"><PaginationLink /></Pagination><Pagination><PaginationLink size="icon-sm" /></Pagination>
<Pagination size="lg"><PaginationPrevious /></Pagination><Pagination><PaginationPrevious size="lg" /></Pagination>

API Reference

Styled Component API

These props are added or materially changed by the installed styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Expand a prop to see named type definitions and framework-specific imports. Follow the Primitive and Runtime links for lower-level behavior props.

Pagination Link

Inherits Button props. Omits `as`, `ref`, and `variant`.

Contains the following additional props:

Prop Type Default Toggle details
isActive boolean —
Description
Applies the active visual state.
Classification
Wrapper prop
size "sm" | "md" | "lg" | "icon-sm" | "icon" | "icon-lg" "icon"
Description
Selects the component's visual size.
Classification
Styled variant

Pagination Previous

Inherits PaginationLink props.

Contains the following additional props:

Prop Type Default Toggle details
size "sm" | "md" | "lg" | "icon-sm" | "icon" | "icon-lg" "md"
Description
Selects the component's visual size.
Classification
Styled variant

Pagination Next

Inherits PaginationLink props.

Contains the following additional props:

Prop Type Default Toggle details
size "sm" | "md" | "lg" | "icon-sm" | "icon" | "icon-lg" "md"
Description
Selects the component's visual size.
Classification
Styled variant

Pagination Ellipsis

Inherits span attributes.

Contains the following additional props:

Prop Type Default Toggle details
size "icon-sm" | "icon" | "icon-lg" "icon"
Description
Selects the component's visual size.
Classification
Styled variant

Changelog

View version history v5.0.0 11 releases

v5.0.0

  • Moved size control from Pagination to each link, navigation control, and ellipsis.
  • Set PaginationLink and PaginationEllipsis to size="icon" by default.
  • Set PaginationPrevious and PaginationNext to size="md" by default so text labels use standard button spacing.
  • Removed the hover movement from the previous and next icons. Button now supplies their icon size.

v4.0.1

  • Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

v4.0.0

  • Moved size ownership to Pagination; remove size from PaginationLink, PaginationPrevious, PaginationNext, and PaginationEllipsis.
  • Migration: <PaginationLink size="icon-sm" /> becomes <Pagination size="sm"><PaginationLink /></Pagination>.

v3.1.0

  • Added contract-generated Astro and React implementations while preserving the component’s existing public API and styling.

v3.0.4

  • Refactor tailwind variants functions into separate variants.ts file

v3.0.2

  • add size prop to PaginationEllipsis
  • Adjust PaginationNext and PaginationPrevious to use button variant props for sizes

v3.0.1

  • Add named slot “icon” to PaginationEllipsis to enable easy icon swapping, and a default slot for the sr-only label
  • Add named slot “icon” to PaginationNext and Pagination Previous to enable easy icon swapping

v3.0.0

  • Now requires the starwind button component installed to make use of the button variants for PaginationLink

v2.1.0

  • Add data-slot attribute to enable global styling updates

v2.0.1

  • Add eslint comments to disable “no-explicit-any” when using Astro special syntax to require a child element

v2.0.0

  • tailwind-variants now implemented. This uses tailwind-merge under the hood to merge Tailwind classes without style conflicts.
  • Removed radius prop now that classes like “rounded-full” can be passed to the components to override, taking advantage of tailwind-variants