EXEPERTAI LAB

Research alpha

Time Machine
EXEPERTAI LAB
GALLERY / COLLECTION
← Browse Astryx gallery
Pagination·component·@astryxdesign/core

Pagination

Pagination lets users step through pages of content. Place it below a table, list, or card grid so users can move forward and backward through results. Pick a variant to match the context: numbered pages for data tables, a count for large lists, compact for tight spaces, or dots for carousels.

Open in Playground @astryxdesign/core/Pagination

Showcases and examples

4 documented examples

Pagination — Variants

All four display variants stacked: dots, compact, count, and pages. A quick visual reference for choosing the right variant.

Preview loads on approachPreview loads on approach
Exact source · pagination-variants
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {useState} from 'react';
import {Pagination} from '@astryxdesign/core/Pagination';
import {Stack} from '@astryxdesign/core/Layout';

export default function PaginationVariants() {
  const [pagesPage, setPagesPage] = useState(3);
  const [countPage, setCountPage] = useState(2);
  const [compactPage, setCompactPage] = useState(5);
  const [dotsPage, setDotsPage] = useState(3);

  return (
    <Stack direction="vertical" gap={5} hAlign="center" style={{width: '100%'}}>
      <Pagination
        page={dotsPage}
        onChange={setDotsPage}
        totalPages={8}
        variant="dots"
      />
      <Pagination
        page={compactPage}
        onChange={setCompactPage}
        totalPages={10}
        variant="compact"
      />
      <Pagination
        page={countPage}
        onChange={setCountPage}
        totalItems={200}
        pageSize={20}
        variant="count"
      />
      <Pagination
        page={pagesPage}
        onChange={setPagesPage}
        totalItems={200}
        pageSize={10}
        variant="pages"
      />
    </Stack>
  );
}

Usage

Pagination lets users step through pages of content. Place it below a table, list, or card grid so users can move forward and backward through results. Pick a variant to match the context: numbered pages for data tables, a count for large lists, compact for tight spaces, or dots for carousels.

  • Place pagination below the content it controls so users see results before navigating.
  • Use the pages variant for data tables where users need to jump to a specific page.
  • Use the count variant with a page size selector when users need to control how many items they see at once.
  • Use the dots variant for carousels and walkthroughs where the total is small and position matters more than a number.
  • Pass totalItems when the total is known so users can see how much content remains.
  • Show pagination when all items fit on a single page; there is nothing to paginate.
  • Use the dots variant for more than about 10 pages; the dots become too small to be useful.
  • Place pagination above the content; users expect it at the bottom.

Typed props

PropType and behavior
pagenumber · required
Current page number (1-based). Page 1 is the first page.
onChange(page: number) => void · required
Called when the page changes.
changeAction(page: number) => void | Promise<void>
Async action on page change. Fires after onChange and uses React transitions for built-in loading state.
totalItemsnumber
Total number of items. Used to calculate page count. Takes precedence over totalPages if both provided.
totalPagesnumber
Total number of pages. Use when you know page count but not item count.
hasMoreboolean
Whether more pages exist after the current one. Use for cursor-based pagination where total is unknown.
pageSizenumber · default 10
Number of items per page. Coerced to a positive integer; non-finite values fall back to the default.
pageSizeOptionsnumber[]
Available page size options. Shows a page size selector dropdown when provided.
onPageSizeChange(pageSize: number) => void
Called when the page size changes. Automatically resets to page 1.
variant'pages' | 'count' | 'compact' | 'dots' | 'input' | 'none' · default 'pages'
Visual variant controlling what appears between prev/next buttons. 'pages' shows page number buttons with ellipsis, 'count' shows 'X-Y of Z' text, 'compact' shows 'Page X of Y', 'dots' shows dot indicators, 'input' shows an editable page-number box with a leading label ('Page [ n ] / N') flanked by first/last buttons by default (the box needs a known total to clamp against, so it is disabled in cursor/hasMore mode), 'none' shows just prev/next buttons.
pageLabelstring
The noun rendered before the editable box in the 'input' variant, e.g. 'Page' or 'Row'. Navigation is always page-based (via onChange); this only relabels the box. Defaults to the localized 'Page'.
hasFirstLastboolean · default true
Whether to show first/last («/») double-chevron buttons flanking prev/next. Only applies to the 'input' variant; omitted when the page count is unknown (cursor/hasMore pagination).
stepnumber · default 1
Number of pages the previous/next buttons advance per click. Clamped to the valid page range, so a step that would overshoot lands on the first/last page. When greater than 1, the buttons' accessible names reflect the stride. Non-integer or values < 1 fall back to 1.
siblingCountnumber · default 1
Number of page buttons to show on each side of the current page. Only applies when variant='pages'.
size'sm' | 'md' · default 'md'
Size of the pagination controls.
isDisabledboolean · default false
Whether the component is disabled.
labelstring · default 'Pagination'
Accessible label for the navigation landmark.
xstyleStyleXStyles
StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.

Anatomy

Pagination · required

Navigation landmark containing the current paging controls and optional page-size selector.

Page-size selector · optional

Optional Selector for choosing how many items appear per page.

First/last buttons · optional

Optional Button controls that jump to the first or last known page.

Previous/next buttons · required

Button controls that move backward or forward through the pages.

Page number button · optional

Button for one directly selectable page in the numbered presentation.

Ellipsis · optional

Visual omission marker between non-adjacent page-number buttons.

Count readout · optional

Text showing the current item range and total item count.

Compact readout · optional

Text showing the current page and total page count.

Dot · optional

Page indicator control that reflects and changes the active page.

Page input label · optional

Leading visible label for the editable page-number field.

Page input · optional

NumberInput used to enter a page directly.

Page input total · optional

Trailing text showing the known total page count.

Theming

Targets

astryx-pagination

Visual props: size, variant

astryx-pagination-dot

Visual props: size

States: active

astryx-pagination-input-label

Visual props: size

astryx-pagination-input-total

Visual props: size