Pagination

A cross-platform React pagination component that adapts page-button display with ellipses for large page counts.

Installation

npm install @xsolla/xui-pagination

Imports

import { Pagination, type PaginationProps, type PaginationSize } from '@xsolla/xui-pagination';

Quick start

import * as React from 'react';
import { Pagination } from '@xsolla/xui-pagination';

export default function QuickStart() {
  const [page, setPage] = React.useState(1);
  return <Pagination currentPage={page} totalPages={10} onPageChange={setPage} />;
}

API Reference

<Pagination>

| Prop | Type | Default | Description | | --- | --- | --- | --- | | currentPage | number | 1 | Current active page (1-indexed). | | totalPages | number | 1 | Total number of pages. | | onPageChange | (page: number) => void | — | Callback fired when a page is clicked. | | siblingCount | number | 1 | Sibling buttons rendered on each side of the current page. | | showNavigation | boolean | true | Show previous/next chevron buttons. | | stretched | boolean | false | Stretch the container to full width and centre items. | | disabled | boolean | false | Disable all interactions. | | size | "sm" \| "md" \| "lg" | "md" | Item size and typography. | | backgroundColor | string | — | Custom background colour for the container. | | testID | string | — | Test identifier. |

Inherits ThemeOverrideProps (themeMode, themeProductContext).

Page-number display

With siblingCount=1 and totalPages=20:

• Page 1 → 1 2 3 4 5 … 20
• Page 10 → 1 … 9 10 11 … 20
• Page 20 → 1 … 16 17 18 19 20

Examples

Sizes

import * as React from 'react';
import { Pagination } from '@xsolla/xui-pagination';

export default function PaginationSizes() {
  const [page, setPage] = React.useState(3);
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
      <Pagination size="sm" currentPage={page} totalPages={10} onPageChange={setPage} />
      <Pagination size="md" currentPage={page} totalPages={10} onPageChange={setPage} />
      <Pagination size="lg" currentPage={page} totalPages={10} onPageChange={setPage} />
    </div>
  );
}

Without navigation

import * as React from 'react';
import { Pagination } from '@xsolla/xui-pagination';

export default function NoNavigation() {
  const [page, setPage] = React.useState(1);
  return (
    <Pagination
      currentPage={page}
      totalPages={8}
      onPageChange={setPage}
      showNavigation={false}
    />
  );
}

More sibling pages

import * as React from 'react';
import { Pagination } from '@xsolla/xui-pagination';

export default function MoreSiblings() {
  const [page, setPage] = React.useState(10);
  return (
    <Pagination
      currentPage={page}
      totalPages={50}
      onPageChange={setPage}
      siblingCount={2}
    />
  );
}

Disabled

import * as React from 'react';
import { Pagination } from '@xsolla/xui-pagination';

export default function DisabledPagination() {
  return <Pagination currentPage={5} totalPages={10} disabled />;
}

Accessibility

• Page buttons have aria-label="Go to page N" and the active page sets aria-current="page".
• Previous/next buttons use aria-label="Previous page" and aria-label="Next page".
• All clickable items have role="button"; disabled or boundary states show a not-allowed cursor and reduced opacity.