Kobalte.v0.12.1

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

PropDescription
pagenumber
The controlled page number of the pagination. (1-indexed)
defaultPagestring
The default page number when initially rendered. (1-indexed)
onPageChange(page: number) => void
Event handler called when the page number changes.
countnumber
The number of pages for the pagination.
siblingCountnumber
The number of siblings to show around the current page item.
showFirstboolean
Whether to always show the first page item.
showLastboolean
Whether to always show the last page item.
fixedItemsboolean | "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).
itemComponentComponent<{page: number}>
The component to render as an item in the Pagination.Items.
ellipsisComponentComponent
The component to render as an ellipsis item in the Pagination.Items.
disabledboolean
Whether the pagination is disabled.
Data attributeDescription
data-disabledPresent when the pagination is disabled.

Pagination.Item

PropDescription
pagenumber
The page number to render.
Data attributeDescription
data-currentPresent when the item is the current page.

Rendered elements

ComponentDefault rendered element
Pagination.Rootdiv
Pagination.Itembutton
Pagination.Ellipsisdiv
Pagination.Previousbutton
Pagination.Nextbutton
Pagination.Itemsnone