# Pagination

A pagination with page navigation, next and previous links.

## Installation

Start from a Svelte 5 application, then install the component package, shared theme, and Bits UI peer:

```bash
pnpm add coss-svelte @coss-svelte/theme bits-ui
```

Import `@coss-svelte/theme/style-coss.css` after Tailwind from the application's global stylesheet.

## Usage

```svelte
<script lang="ts">
import {
	Pagination,
	PaginationContent,
	PaginationEllipsis,
	PaginationItem,
	PaginationLink,
	PaginationNext,
	PaginationPrevious,
} from "coss-svelte";
</script>

<Pagination>
	<PaginationContent>
		<PaginationItem><PaginationPrevious href="#" /></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="#" /></PaginationItem>
	</PaginationContent>
</Pagination>

```

## Anatomy

- `Pagination`
- `PaginationContent`
- `PaginationEllipsis`
- `PaginationItem`
- `PaginationLink`
- `PaginationNext`
- `PaginationNextButton`
- `PaginationPage`
- `PaginationPrevious`
- `PaginationPrevButton`

## API Reference

### Pagination

A pagination with page navigation, next and previous links.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bind:page` | `number` | `2` | Current page. Bind with `bind:page`. |
| `pages` | `number` | `5` | Total number of pages to render when count is not provided. |
| `count` | `number` | `totalPages` | Total item count used to calculate pagination. |
| `perPage` | `number` | - | Items per page used with count to calculate page totals. |

**Composition and refs**

- `children: Snippet<[PaginationSnippetProps]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI Pagination.Root](https://bits-ui.com/docs/components/pagination#root).

### PaginationContent

Wraps the primary content for the parent component.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <ul> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### PaginationEllipsis

Represents skipped pages in pagination.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <span> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### PaginationItem

Renders one selectable or repeated item.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <li> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### PaginationLink

Renders a link-styled navigation item.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isActive` | `boolean` | `false` | Marks the item as the current or selected navigation target. |

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <a> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### PaginationNext

Renders navigation to the next page.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | `""` | Renders the component as a link target when provided. |

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <span> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### PaginationNextButton

Renders a button-shaped control for the parent component.

**Composition and refs**

- `children: Snippet<[]>`
- `child: Snippet<[{ props: Record<string, unknown> }]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI Pagination.NextButton](https://bits-ui.com/docs/components/pagination#next-button).

### PaginationPage

Renders one numbered page control.

**Composition and refs**

- `children: Snippet<[]>`
- `child: Snippet<[{ props: Record<string, unknown> }]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI Pagination.Page](https://bits-ui.com/docs/components/pagination#page).

### PaginationPrevious

Renders navigation to the previous page.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | `""` | Renders the component as a link target when provided. |

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <span> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### PaginationPrevButton

Renders a button-shaped control for the parent component.

**Composition and refs**

- `children: Snippet<[]>`
- `child: Snippet<[{ props: Record<string, unknown> }]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI Pagination.PrevButton](https://bits-ui.com/docs/components/pagination#prev-button).

## Implementation Details

| Field | Value |
| --- | --- |
| Status | Stable |
| Foundation | bits |
| Category | Layout & Navigation |
| Particles | 3 |

## Status

Stable for the current coss-svelte surface.

## Agent Notes

- Import Svelte exports directly from `coss-svelte`.
- This is Svelte 5 code: use `class`, lowercase event properties, runes, snippets, and documented `bind:*` contracts. Do not emit JSX, React hooks, `className`, `asChild`, or Base UI imports.
- Prefer this route's example and generated API table over React COSS snippets; COSS React particles are design references only.
- The copy-and-own registry is a preview. Inspect `/r/pagination.json` for the complete local file and dependency closure.
- Pagination is stable in the current source catalog.