CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-rc-pagination

pagination ui component for react

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

pagination.mddocs/

Pagination Component

The Pagination component provides comprehensive pagination functionality for React applications, supporting both controlled and uncontrolled modes with extensive customization options.

Import

import Pagination from 'rc-pagination';
import type { PaginationProps } from 'rc-pagination';
import 'rc-pagination/assets/index.css';

Complete API

/**
 * Main pagination component props interface
 * Extends React ARIA attributes for accessibility
 */
interface PaginationProps extends React.AriaAttributes {
  // Core pagination control
  current?: number;
  defaultCurrent?: number;
  total?: number;
  pageSize?: number;
  defaultPageSize?: number;
  
  // Event handlers
  onChange?: (page: number, pageSize: number) => void;
  onShowSizeChange?: (current: number, size: number) => void;
  
  // Display options
  hideOnSinglePage?: boolean;
  showSizeChanger?: boolean;
  showQuickJumper?: boolean | object;
  showTotal?: (total: number, range: [number, number]) => React.ReactNode;
  showLessItems?: boolean;
  showPrevNextJumpers?: boolean;
  showTitle?: boolean;
  simple?: boolean | { readOnly?: boolean };
  
  // Styling and layout
  className?: string;
  style?: React.CSSProperties;
  prefixCls?: string;
  selectPrefixCls?: string;
  align?: 'start' | 'center' | 'end';
  disabled?: boolean;
  
  // Icons
  prevIcon?: React.ComponentType | React.ReactNode;
  nextIcon?: React.ComponentType | React.ReactNode;
  jumpPrevIcon?: React.ComponentType | React.ReactNode;
  jumpNextIcon?: React.ComponentType | React.ReactNode;
  
  // Size options
  pageSizeOptions?: number[];
  totalBoundaryShowSizeChanger?: number;
  
  // Customization
  itemRender?: (page: number, type: 'page' | 'prev' | 'next' | 'jump-prev' | 'jump-next', element: React.ReactNode) => React.ReactNode;
  sizeChangerRender?: (info: SizeChangerRenderInfo) => React.ReactNode;
  buildOptionText?: (value: number | string) => string;
  
  // Internationalization
  locale?: PaginationLocale;
  
  // Accessibility
  role?: React.AriaRole | undefined;
}

/**
 * Size changer render function parameters
 */
interface SizeChangerRenderInfo {
  disabled: boolean;                                    // Whether the size changer is disabled
  size: number;                                        // Current page size
  onSizeChange: (value: string | number) => void;     // Handler for size changes
  'aria-label': string;                               // ARIA label for accessibility
  className: string;                                  // CSS class name
  options: {                                          // Available size options
    label: string;                                    // Display label for the option
    value: string | number;                          // Value for the option
  }[];
}

Core Pagination Properties

Page Control

current (number, optional) Current active page number. When provided, the component operates in controlled mode.

defaultCurrent (number, optional, default: 1) Initial page number for uncontrolled mode.

total (number, optional, default: 0) Total number of items across all pages.

pageSize (number, optional) Number of items per page. When provided, the component operates in controlled mode.

defaultPageSize (number, optional, default: 10) Initial page size for uncontrolled mode.

Event Handlers

onChange (function, optional) Callback fired when the page number or page size changes.

(page: number, pageSize: number) => void

onShowSizeChange (function, optional) Callback fired when the page size changes via the size changer.

(current: number, size: number) => void

Display Configuration

Visibility Options

hideOnSinglePage (boolean, optional, default: false) Hide the pagination component when there is only one page.

showSizeChanger (boolean, optional) Show the page size selector. Can be boolean or an object with select component options.

  • false: Never show size changer
  • true: Always show size changer
  • Auto: Shows when total > totalBoundaryShowSizeChanger (default 50)

showQuickJumper (boolean | object, optional, default: false) Show the quick page jumper input.

  • true: Show basic quick jumper
  • { goButton: true }: Show with go button
  • { goButton: 'Go' }: Show with custom go button text

showTotal (function, optional) Custom function to display total information.

(total: number, range: [number, number]) => React.ReactNode

showLessItems (boolean, optional, default: false) Show fewer page number buttons to save space.

showPrevNextJumpers (boolean, optional, default: true) Show the jump-previous and jump-next buttons (... buttons).

showTitle (boolean, optional, default: true) Show title attributes on page buttons for accessibility.

Layout and Styling

align ('start' | 'center' | 'end', optional) Horizontal alignment of pagination component.

className (string, optional) Custom CSS class name for the pagination wrapper.

style (React.CSSProperties, optional) Inline styles for the pagination wrapper.

prefixCls (string, optional, default: 'rc-pagination') CSS class prefix for pagination elements.

selectPrefixCls (string, optional, default: 'rc-select') CSS class prefix for the size selector component.

disabled (boolean, optional, default: false) Disable the entire pagination component.

Usage Examples

Basic Controlled Pagination

import React, { useState } from 'react';
import Pagination from 'rc-pagination';

function DataTable() {
  const [current, setCurrent] = useState(1);
  const [pageSize, setPageSize] = useState(10);
  const totalItems = 500;

  const handleChange = (page: number, size: number) => {
    setCurrent(page);
    setPageSize(size);
    // Fetch data for the new page
    fetchData(page, size);
  };

  return (
    <div>
      {/* Your data display */}
      <Pagination
        current={current}
        pageSize={pageSize}
        total={totalItems}
        onChange={handleChange}
        showSizeChanger
        showQuickJumper
        showTotal={(total, range) => 
          `${range[0]}-${range[1]} of ${total} items`
        }
      />
    </div>
  );
}

Uncontrolled Pagination

function SimpleList() {
  const handlePageChange = (page: number, pageSize: number) => {
    console.log(`Page ${page}, Size ${pageSize}`);
    // Handle page change without state management
    loadPageData(page, pageSize);
  };

  return (
    <Pagination
      defaultCurrent={1}
      defaultPageSize={20}
      total={1000}
      onChange={handlePageChange}
      hideOnSinglePage
    />
  );
}

Simple Mode

function MobilePagination() {
  const [current, setCurrent] = useState(1);

  return (
    <Pagination
      current={current}
      total={100}
      pageSize={10}
      simple
      onChange={(page) => setCurrent(page)}
    />
  );
}

Custom Total Display

function CustomTotalPagination() {
  return (
    <Pagination
      current={1}
      total={1500}
      pageSize={25}
      showTotal={(total, range) => (
        <span>
          Showing <strong>{range[0]}</strong> to <strong>{range[1]}</strong> of{' '}
          <strong>{total}</strong> results
        </span>
      )}
      onChange={(page, pageSize) => {
        // Handle change
      }}
    />
  );
}

With Custom Page Size Options

function CustomSizeOptions() {
  return (
    <Pagination
      current={1}
      total={1000}
      pageSize={20}
      pageSizeOptions={[10, 20, 50, 100, 200]}
      showSizeChanger
      onChange={(page, pageSize) => {
        // Handle change
      }}
      onShowSizeChange={(current, size) => {
        console.log(`Current page: ${current}, New size: ${size}`);
      }}
    />
  );
}

Aligned Pagination

function AlignedPagination() {
  return (
    <div>
      {/* Center aligned */}
      <Pagination
        current={1}
        total={100}
        align="center"
        onChange={() => {}}
      />
      
      {/* Right aligned */}
      <Pagination
        current={1}
        total={100}
        align="end"
        onChange={() => {}}
      />
    </div>
  );
}

Disabled State

function DisabledPagination() {
  return (
    <Pagination
      current={5}
      total={100}
      disabled
      onChange={() => {}}
    />
  );
}

Advanced Features

Auto Size Changer Display

The totalBoundaryShowSizeChanger property (default: 50) automatically shows or hides the size changer based on the total number of items:

<Pagination
  current={1}
  total={25} // Size changer hidden (< 50)
  totalBoundaryShowSizeChanger={30}
  onChange={() => {}}
/>

<Pagination
  current={1}
  total={100} // Size changer shown (>= 50)
  onChange={() => {}}
/>

Responsive Behavior

Use showLessItems for compact display on smaller screens:

const isMobile = window.innerWidth < 768;

<Pagination
  current={current}
  total={1000}
  showLessItems={isMobile}
  onChange={onChange}
/>

Accessibility

The component includes built-in accessibility features:

  • ARIA attributes for screen readers
  • Keyboard navigation support
  • Semantic HTML structure
  • Configurable role attribute
  • Title attributes for page buttons (controllable via showTitle)
<Pagination
  current={1}
  total={100}
  role="navigation"
  aria-label="Data table pagination"
  showTitle={true}
  onChange={() => {}}
/>

Install with Tessl CLI

npx tessl i tessl/npm-rc-pagination

docs

advanced-customization.md

index.md

internationalization.md

pagination.md

tile.json