Skip to main content
Kobalte
ComponentsChangelog

Pagination

Since v0.10.0@kobalte/core/paginationSource

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

Import

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.
<Pagination>
  <Pagination.Previous/>
  <Pagination.Items/>
  <Pagination.Next/>
</Select>

Example

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


export function BasicExample() {
  return (
    <Pagination
      class={style.pagination__root}
      count={10}
      itemComponent={(props) => (
        <Pagination.Item class={style.pagination__item} page={props.page}>
          {props.page}
        </Pagination.Item>
      )}
      ellipsisComponent={() => (
        <Pagination.Ellipsis class={style.pagination__ellipsis}>
          ...
        </Pagination.Ellipsis>
      )}
    >
      <Pagination.Previous class={style.pagination__item}>
        Previous
      </Pagination.Previous>
      <Pagination.Items />
      <Pagination.Next class={style.pagination__item}>Next</Pagination.Next>
    </Pagination>
  );
}
.pagination__root > ul {
  display: inline-flex;
  align-items: center;
  justify-content: space-between;
  gap: 0.5rem;
}


.pagination__item {
  appearance: none;
  display: inline-flex;
  justify-content: center;
  align-items: center;
  height: 40px;
  width: auto;
  outline: none;
  border-radius: 6px;
  padding: 0 16px;
  background-color: white;
  color: hsl(240 4% 16%);
  font-size: 16px;
  line-height: 0;
  transition:
    250ms background-color,
    250ms color,
    250ms border-color;
  cursor: pointer;
  font-variant-numeric: tabular-nums;
  border: 1px solid hsl(240 6% 90%);
}


.pagination__ellipsis {
  display: inline-flex;
  justify-content: center;
  align-items: center;
  height: 40px;
  width: auto;
  outline: none;
  border-radius: 6px;
  padding: 0 16px;
  background-color: white;
  color: hsl(240 4% 16%);
  font-size: 16px;
  line-height: 0;
  cursor: default;
  border: 1px solid hsl(240 6% 90%);
}


.pagination__item[aria-current="page"] {
  background-color: hsl(200 98% 39%);
  color: white;
}


.pagination__item:hover {
  background-color: hsl(200 98% 39%);
  color: white;
}


.pagination__item:focus-visible {
  outline: 2px solid hsl(200 98% 39%);
  outline-offset: 2px;
  color: white;
}


.pagination__item:active {
  background-color: hsl(201 90% 27%);
  color: white;
}


[data-theme*="dark"] .pagination__item {
  background-color: hsl(240 4% 16%);
  border: 1px solid hsl(240 5% 34%);
  color: hsl(0 100% 100% / 0.9);
}


[data-theme*="dark"] .pagination__ellipsis {
  background-color: hsl(240 4% 16%);
  border: 1px solid hsl(240 5% 34%);
  color: hsl(0 100% 100% / 0.9);
}


[data-theme*="dark"] .pagination__item[aria-current="page"] {
  background-color: hsl(201 96% 32%);
  color: hsla(0 100% 100% / 0.9);
}


[data-theme*="dark"] .pagination__item:hover {
  border-color: hsl(240 4% 46%);
}


[data-theme*="dark"] .pagination__item:active {
  background-color: hsl(199 89% 48%);
}

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.

<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.

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.

<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.

<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.

<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.

<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).

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
Paginationdiv
Pagination.Itembutton
Pagination.Ellipsisdiv
Pagination.Previousbutton
Pagination.Nextbutton
Pagination.Itemsnone

Last updated: 7/16/26, 7:09 AM