Pagination

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

Import

ts
import { Pagination } from "@kobalte/core";

ts
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.Root: 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.

tsx
<Pagination.Root>
  <Pagination.Previous/>
  <Pagination.Items/>
  <Pagination.Next/>
</Select.Root>

tsx
<Pagination.Root>
  <Pagination.Previous/>
  <Pagination.Items/>
  <Pagination.Next/>
</Select.Root>

Example

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.

tsx
<Pagination.Root
	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.Root>

tsx
<Pagination.Root
	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.Root>

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.

tsx
import { createSignal } from "solid-js";
export function ControlledExample() {
	const [page, setPage] = createSignal(4);
	return (
		<Pagination.Root
			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.Root>
	);
}

tsx
import { createSignal } from "solid-js";
export function ControlledExample() {
	const [page, setPage] = createSignal(4);
	return (
		<Pagination.Root
			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.Root>
	);
}

Next / Previous buttons example

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

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

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

First / Last item example

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

tsx
<Pagination.Root
	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.Root>

tsx
<Pagination.Root
	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.Root>

Siblings example

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

tsx
<Pagination.Root
	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.Root>

tsx
<Pagination.Root
	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.Root>

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.

tsx
<Pagination.Root
	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.Root>

tsx
<Pagination.Root
	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.Root>

API Reference

Pagination.Root

Prop	Description
page	`number` The controlled page number of the pagination. (1-indexed)
defaultPage	`string` The default page number when initially rendered. (1-indexed)
onPageChange	`(page: number) => void` Event handler called when the page number changes.
count	`number` The number of pages for the pagination.
siblingCount	`number` The number of siblings to show around the current page item.
showFirst	`boolean` Whether to always show the first page item.
showLast	`boolean` Whether to always show the last page item.
fixedItems	`boolean \| "no-ellipsis"` 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}>` The component to render as an item in the `Pagination.Items`.
ellipsisComponent	`Component` The component to render as an ellipsis item in the `Pagination.Items`.
disabled	`boolean` Whether the pagination is disabled.

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

Pagination.Item

Prop	Description
page	`number` 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.Root`	`div`
`Pagination.Item`	`button`
`Pagination.Ellipsis`	`div`
`Pagination.Previous`	`button`
`Pagination.Next`	`button`
`Pagination.Items`	none