Pagination

The Pagination component allows users to navigate through a series of content separated into discrete pages.

Installation

$ cbui-cli install @crossbuildui/pagination

To get started, please make sure you have installed cbui-cli globally and authenticated your account. This will ensure you can access all the necessary features.

View documents

Import

index.tsx

import { Pagination } from '@/crossbuildui/pagination';
import Icon from 'react-native-vector-icons/MaterialIcons'; // If using custom controls with icons

The Pagination component uses react-native-vector-icons for its default control icons. Ensure this library is installed and linked in your React Native project if you plan to use the default icons or custom icons from this library.

Basic Usage

Provide the total number of pages and an optional initialPage.

index.tsx

<Pagination total={10} initialPage={1} />

Controlled vs. Uncontrolled

The Pagination can be uncontrolled using initialPage or controlled using the page prop along with an onChange handler.

index.tsx

const [currentPage, setCurrentPage] = useState(3);

<Pagination
  total={20}
  page={currentPage}
  onChange={setCurrentPage}
/>

Variants & Colors

Pagination supports flat (default), bordered, light, and faded variants. The color prop applies to the active item.

index.tsx

// Flat (default)
<Pagination total={7} color="primary" />

// Bordered
<Pagination total={7} variant="bordered" color="secondary" />

// Light
<Pagination total={7} variant="light" color="success" />

// Faded
<Pagination total={7} variant="faded" color="warning" />

Sizes

Adjust the size of pagination items using the size prop: sm, md (default), and lg.

index.tsx

<Pagination total={5} size="sm" />
<Pagination total={5} size="md" /> // Default
<Pagination total={5} size="lg" />

Compact Mode

Use isCompact for a more condensed pagination display, typically showing fewer page numbers.

index.tsx

<Pagination total={15} isCompact />
<Pagination total={15} isCompact showControls={false} />

Looping

Enable loop to allow navigation from the last page to the first, and vice-versa.

index.tsx

<Pagination total={5} initialPage={1} loop />

Custom Controls

Customize or hide the previous/next controls using prevControlContent, nextControlContent, and showControls.

index.tsx

<Pagination
  total={8}
  prevControlContent={<Icon name="arrow-back" size={20} />}
  nextControlContent={<Icon name="arrow-forward" size={20} />}
/>

// Hiding controls
<Pagination total={8} showControls={false} />

Dots Jump Behavior

The dotsJump prop controls how many pages are skipped when an ellipsis (...) button is pressed.

index.tsx

<Pagination total={25} initialPage={1} dotsJump={3} siblings={1} boundaries={1} />
{/* Click '...' to jump 3 pages instead of default 5 */} 

Siblings and Boundaries

Control the number of page numbers displayed around the current page (siblings) and at the start/end (boundaries) of the pagination list.

index.tsx

<Pagination total={30} initialPage={15} siblings={2} boundaries={2} />
{/* Shows 2 siblings on each side and 2 boundary pages at start/end */}

<Pagination total={30} initialPage={15} siblings={0} boundaries={1} />
{/* Shows only current page and 1 boundary page at start/end, with dots */} 

Props Overview

PROP	TYPE	DEFAULT	DESCRIPTION
`total`	`number`	-	The total number of pages. Required.
`variant`	`'flat' \| 'bordered' \| 'light' \| 'faded'`	`'flat'`	Visual style.
`color`	`ThemeColorName`	`'primary'`	Thematic color for active item.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Size of items.
`radius`	`'none' \| 'sm' \| 'md' \| 'lg' \| 'full'`	`'md'`	Border radius for items.
`dotsJump`	`number`	5	Number of pages to jump on '...' click.
`initialPage`	`number`	1	Initial page (uncontrolled).
`page`	`number`	-	Current page (controlled).
`onChange`	`(page: number) => void`	-	Callback on page change.
`siblings`	`number`	1	Pages before/after current.
`boundaries`	`number`	1	Pages at start/end.
`loop`	`boolean`	`false`	Loop pagination.
`isCompact`	`boolean`	`false`	Compact style.
`isDisabled`	`boolean`	`false`	Disable pagination.
`showControls`	`boolean`	`true`	Show prev/next controls.
`disableAnimation`	`boolean`	`false`	Disable animation (not implemented).
`styles`	`PaginationSlotsStyles`	-	Custom styles for internal slots (e.g., `item`, `activeItem`, `wrapper`).
`style`	`StyleProp<ViewStyle>`	-	Style for the outermost container.
`prevControlContent`	`ReactNode`	Default Icon	Custom content for the "previous" control button.
`nextControlContent`	`ReactNode`	Default Icon	Custom content for the "next" control button.

Styling

Customize the appearance using:

style prop on Pagination for the outermost container.
styles prop on Pagination for internal slots. Available slots are:
- base: The main container view.
- wrapper: The view wrapping all items (pages, dots, controls).
- item: Each individual page number item (Pressable).
- itemText: Text inside each page number item.
- activeItem: The currently active page number item.
- activeItemText: Text inside the active page number item.
- dotsItem: The ellipsis (...) item.
- dotsItemText: Text inside the ellipsis item.
- controlItem: The previous/next control buttons.
- controlItemContent: Style for icon/text inside control buttons (not directly stylable if custom ReactNode is provided).

index.tsx

<Pagination
  total={10}
  style={{ marginVertical: 20, paddingHorizontal: 10 }} // Style for the outermost container
  styles={{
    base: { backgroundColor: '#e0e0e0', borderRadius: 12 },
    wrapper: { gap: 8 }, // Custom gap between items
    item: { borderWidth: 2, borderColor: 'blue' },
    activeItem: { backgroundColor: 'green', borderColor: 'darkgreen' },
    itemText: { color: 'black' },
    activeItemText: { color: 'white', fontWeight: 'bold' },
    controlItem: { backgroundColor: 'lightgray' },
    dotsItem: { opacity: 0.7 }
  }}
/>

Accessibility

The Pagination component is designed with accessibility in mind:

The root view has accessibilityRole="toolbar" and an accessibilityLabel of "Pagination controls".
Each page item Pressable has accessibilityRole="button".
Page items include an accessibilityLabel indicating the page number and if it's the current page (e.g., "Go to page 5, current page").
Dots items have an accessibilityLabel of "Jump pages".
Control buttons (previous/next) have appropriate accessibilityLabels (e.g., "Previous page", "Next page").
accessibilityState (selected, disabled) is applied to page items and controls.

Breadcrumbs Accordion