Pagination

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

Pagination splits a large set of results into pages and lets users move between them. It shows the current page, nearby pages, and previous/next arrows, collapsing long ranges with an ellipsis.

When to use

• To break a long list, table, or set of results into navigable pages
• When the total number of pages is known and users may jump to a specific one

When not to use

• For continuously loading content — use infinite scroll or a "Load more" instead
• For step-by-step flows — use Progress step or a Stepper instead
• When all results comfortably fit on one page

Content guidelines

Always make the current page clearly distinct from the rest.

Collapse long ranges with "…", keeping the first, last, current, and neighbouring pages visible.

Use page numbers as the main affordance and the arrows for moving one page at a time.

Behaviour guidelines

Basic shows a small fixed range of pages with arrows.

Advanced-first / -between / -last adapt which numbers and ellipses appear based on whether the current page is near the start, middle, or end.

Previous/next move one page and are disabled at the first and last page.

Selecting a number jumps to that page; the current page is active and not clickable. Size M and S scale the whole control.

Accessibility

Expose pagination as a navigation landmark with an accessible name (e.g. "Pagination").

Mark the current page with aria-current="page".

Label the previous/next arrows and disable them at the boundaries; treat the ellipsis as decorative, not a focus stop.

Keep it keyboard-operable with a visible focus indicator.

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.