# Pagination

Allows the user to select a specific page from a range of pages.

## Import

```
Copyts
import { Pagination } from "@kobalte/core/pagination";
// or
import { Root, Item, ... } from "@kobalte/core/pagination";
// or (deprecated)
import { Pagination } from "@kobalte/core";
```

```
Copyts
import { Pagination } from "@kobalte/core/pagination";
// or
import { Root, Item, ... } from "@kobalte/core/pagination";
// or (deprecated)
import { Pagination } from "@kobalte/core";
```

## Features

- Labeling support for accessibility.
- Tab focus management.
- Can be controlled or uncontrolled.
- Customizable appearance.

## Anatomy

The pagination consists of:

- **Pagination:** The root container for the pagination component.
- **Pagination.Item:** An item of the pagination.
- **Pagination.Ellipsis:** Ellipsis item of the pagination.
- **Pagination.Previous:** Previous button of the pagination.
- **Pagination.Next:** Next button of the pagination.
- **Pagination.Items:** Contains the list of items and allows a user to select one of them.

```
Copytsx
<Pagination>
  <Pagination.Previous/>
  <Pagination.Items/>
  <Pagination.Next/>
</Select>
```

```
Copytsx
<Pagination>
  <Pagination.Previous/>
  <Pagination.Items/>
  <Pagination.Next/>
</Select>
```

## Example

index.tsxstyle.css

```
Copytsx
import { Pagination } from "@kobalte/core/pagination";
import "./style.css";

function App() {
  return (
  <Pagination
    class="pagination__root"
    count={10}
    itemComponent={props => (
      <Pagination.Item class="pagination__item" page={props.page}>{props.page}</Pagination.Item>
      )}
    ellipsisComponent={() => (
      <Pagination.Ellipsis class="pagination__ellipsis">...</Pagination.Ellipsis>
      )}
    >
      <Pagination.Previous class="pagination__item">Previous</Pagination.Previous>
      <Pagination.Items/>
      <Pagination.Next class="pagination__item">Next</Pagination.Next>
    </Pagination>
  );
}
```

```
Copytsx
import { Pagination } from "@kobalte/core/pagination";
import "./style.css";

function App() {
  return (
  <Pagination
    class="pagination__root"
    count={10}
    itemComponent={props => (
      <Pagination.Item class="pagination__item" page={props.page}>{props.page}</Pagination.Item>
      )}
    ellipsisComponent={() => (
      <Pagination.Ellipsis class="pagination__ellipsis">...</Pagination.Ellipsis>
      )}
    >
      <Pagination.Previous class="pagination__item">Previous</Pagination.Previous>
      <Pagination.Items/>
      <Pagination.Next class="pagination__item">Next</Pagination.Next>
    </Pagination>
  );
}
```

## Usage

### Default value

An initial, uncontrolled page can be provided using the `defaultPage` prop, which accepts a number smaller or equal to the `count` and starts at 1.

```
Copytsx
<Pagination
	count={10}
	defaultPage={4}
	itemComponent={props => <Pagination.Item page={props.page}>{props.page}</Pagination.Item>}
	ellipsisComponent={() => <Pagination.Ellipsis>...</Pagination.Ellipsis>}
>
	<Pagination.Previous>Previous</Pagination.Previous>
	<Pagination.Items />
	<Pagination.Next>Next</Pagination.Next>
</Pagination>
```

```
Copytsx
<Pagination
	count={10}
	defaultPage={4}
	itemComponent={props => <Pagination.Item page={props.page}>{props.page}</Pagination.Item>}
	ellipsisComponent={() => <Pagination.Ellipsis>...</Pagination.Ellipsis>}
>
	<Pagination.Previous>Previous</Pagination.Previous>
	<Pagination.Items />
	<Pagination.Next>Next</Pagination.Next>
</Pagination>
```

### Controlled value

The `page` prop, which accepts a page number, can be used to make the value controlled. The `onPageChange` event is fired when the user selects an item, and receives the new page number.

```
Copytsx
import { createSignal } from "solid-js";

export function ControlledExample() {
	const [page, setPage] = createSignal(4);

	return (
		<Pagination
			page={page()}
			onPageChange={setPage}
			count={10}
			itemComponent={props => <Pagination.Item page={props.page}>{props.page}</Pagination.Item>}
			ellipsisComponent={() => <Pagination.Ellipsis>...</Pagination.Ellipsis>}
		>
			<Pagination.Previous>Previous</Pagination.Previous>
			<Pagination.Items />
			<Pagination.Next>Next</Pagination.Next>
		</Pagination>
	);
}
```

```
Copytsx
import { createSignal } from "solid-js";

export function ControlledExample() {
	const [page, setPage] = createSignal(4);

	return (
		<Pagination
			page={page()}
			onPageChange={setPage}
			count={10}
			itemComponent={props => <Pagination.Item page={props.page}>{props.page}</Pagination.Item>}
			ellipsisComponent={() => <Pagination.Ellipsis>...</Pagination.Ellipsis>}
		>
			<Pagination.Previous>Previous</Pagination.Previous>
			<Pagination.Items />
			<Pagination.Next>Next</Pagination.Next>
		</Pagination>
	);
}
```

### Next / Previous buttons example

The appearance can be customized by omitting the Next and Previous Button.

```
Copytsx
<Pagination
	count={10}
	itemComponent={props => <Pagination.Item page={props.page}>{props.page}</Pagination.Item>}
	ellipsisComponent={() => <Pagination.Ellipsis>...</Pagination.Ellipsis>}
>
	<Pagination.Items />
</Pagination>
```

```
Copytsx
<Pagination
	count={10}
	itemComponent={props => <Pagination.Item page={props.page}>{props.page}</Pagination.Item>}
	ellipsisComponent={() => <Pagination.Ellipsis>...</Pagination.Ellipsis>}
>
	<Pagination.Items />
</Pagination>
```

### First / Last item example

The First and Last item can be hidden instead of displaying at all times.

```
Copytsx
<Pagination
	count={10}
	showFirst={false}
	showLast={false}
	itemComponent={props => <Pagination.Item page={props.page}>{props.page}</Pagination.Item>}
	ellipsisComponent={() => <Pagination.Ellipsis>...</Pagination.Ellipsis>}
>
	<Pagination.Previous>Previous</Pagination.Previous>
	<Pagination.Items />
	<Pagination.Next>Next</Pagination.Next>
</Pagination>
```

```
Copytsx
<Pagination
	count={10}
	showFirst={false}
	showLast={false}
	itemComponent={props => <Pagination.Item page={props.page}>{props.page}</Pagination.Item>}
	ellipsisComponent={() => <Pagination.Ellipsis>...</Pagination.Ellipsis>}
>
	<Pagination.Previous>Previous</Pagination.Previous>
	<Pagination.Items />
	<Pagination.Next>Next</Pagination.Next>
</Pagination>
```

### Siblings example

The number of items around the current page item can be customized.

```
Copytsx
<Pagination
	count={10}
	siblingCount={2}
	itemComponent={props => <Pagination.Item page={props.page}>{props.page}</Pagination.Item>}
	ellipsisComponent={() => <Pagination.Ellipsis>...</Pagination.Ellipsis>}
>
	<Pagination.Previous>Previous</Pagination.Previous>
	<Pagination.Items />
	<Pagination.Next>Next</Pagination.Next>
</Pagination>
```

```
Copytsx
<Pagination
	count={10}
	siblingCount={2}
	itemComponent={props => <Pagination.Item page={props.page}>{props.page}</Pagination.Item>}
	ellipsisComponent={() => <Pagination.Ellipsis>...</Pagination.Ellipsis>}
>
	<Pagination.Previous>Previous</Pagination.Previous>
	<Pagination.Items />
	<Pagination.Next>Next</Pagination.Next>
</Pagination>
```

### Fixed Items example

The total number of items can be fixed to avoid content shift. If ellipsis are disabled (by returning an empty component) use `fixedItems="no-ellipsis"` instead.

```
Copytsx
<Pagination
	count={10}
	fixedItems
	itemComponent={props => <Pagination.Item page={props.page}>{props.page}</Pagination.Item>}
	ellipsisComponent={() => <Pagination.Ellipsis>...</Pagination.Ellipsis>}
>
	<Pagination.Previous>Previous</Pagination.Previous>
	<Pagination.Items />
	<Pagination.Next>Next</Pagination.Next>
</Pagination>
```

```
Copytsx
<Pagination
	count={10}
	fixedItems
	itemComponent={props => <Pagination.Item page={props.page}>{props.page}</Pagination.Item>}
	ellipsisComponent={() => <Pagination.Ellipsis>...</Pagination.Ellipsis>}
>
	<Pagination.Previous>Previous</Pagination.Previous>
	<Pagination.Items />
	<Pagination.Next>Next</Pagination.Next>
</Pagination>
```

## API Reference

### Pagination

`Pagination` is equivalent to the `Root` import from `@kobalte/core/pagination` (and deprecated `Pagination.Root`).

| Prop | Description |
| --- | --- |
| page | `number`<br> The controlled page number of the pagination. (1-indexed) |
| defaultPage | `string`<br> The default page number when initially rendered. (1-indexed) |
| onPageChange | `(page: number) => void`<br> Event handler called when the page number changes. |
| count | `number`<br> The number of pages for the pagination. |
| siblingCount | `number`<br> The number of siblings to show around the current page item. |
| showFirst | `boolean`<br> Whether to always show the first page item. |
| showLast | `boolean`<br> Whether to always show the last page item. |
| fixedItems | `boolean | "no-ellipsis"`<br> Whether to always show the same number of items (to avoid content shift). Special value: `"no-ellipsis"` does not count the ellipsis as an item (used when ellipsis are disabled). |
| itemComponent | `Component<{page: number}>`<br> The component to render as an item in the `Pagination.Items`. |
| ellipsisComponent | `Component`<br> The component to render as an ellipsis item in the `Pagination.Items`. |
| disabled | `boolean`<br> Whether the pagination is disabled. |

| Data attribute | Description |
| --- | --- |
| data-disabled | Present when the pagination is disabled. |

### Pagination.Item

| Prop | Description |
| --- | --- |
| page | `number`<br> The page number to render. |

| Data attribute | Description |
| --- | --- |
| data-current | Present when the item is the current page. |

## Rendered elements

| Component | Default rendered element |
| --- | --- |
| `Pagination` | `div` |
| `Pagination.Item` | `button` |
| `Pagination.Ellipsis` | `div` |
| `Pagination.Previous` | `button` |
| `Pagination.Next` | `button` |
| `Pagination.Items` | none |

Previous[←Number Field](https://kobalte.dev/docs/core/components/number-field)Next[Popover→](https://kobalte.dev/docs/core/components/popover)