Pagination

Move through page indexes or tabular page ranges with native controls.

This guide covers Material UI Core with the default Emotion engine; extensions and additional demos are explicitly classified.

Use case and business boundary

Pagination is one-based; TablePagination is zero-based. Neither fetches rows or stores total counts.

Native composition and scope

Pagination, PaginationItem, TablePagination, TablePaginationActions

Preserve native Material UI composition and types; do not substitute JGuang UI/Base UI/Radix APIs. Example entries are not extra components.

Native installation and initialization

npm install @mui/material@9.4.0 @emotion/react@11.14.0 @emotion/styled@11.14.1

Use native npm and Emotion, not an invented JGuang UI Registry URL. Place examples inside native ThemeProvider; choose CssBaseline or ScopedCssBaseline for the project. Inspect React, existing providers, lockfile and SSR first. Never overwrite files or conceal peer conflicts. This batch verified React 19.2.8; React 18 and below require matching react-is. See the included bilingual setup guide.

Practical native parameters

These selected parameters are not a flattened universal API. Preserve the native declaring owner, slot structure, nullable values and generics.

Runnable native examples

Machine keys select example entries, not universal variant props. Native demo JSX/data stay unchanged; JGuang-authored acceptance fixtures are explicitly labelled.

• Basic pagination · BasicPagination · upstream native demo
• Outlined pagination · PaginationOutlined · upstream native demo
• Rounded pagination · PaginationRounded · upstream native demo
• Pagination size · PaginationSize · upstream native demo
• Buttons · PaginationButtons · upstream native demo
• Custom icons · CustomIcons · upstream native demo
• Pagination ranges · PaginationRanges · upstream native demo
• Controlled pagination · PaginationControlled · upstream native demo
• usePagination · UsePagination · upstream native demo
• Table pagination · TablePaginationDemo · upstream native demo

Explicitly unsupported additional examples

These remain in the upstream inventory, not silently skipped or presented as working previews. Additional dependency/framework acceptance is required.

• Router integration · PaginationLink: react-router

Actual usage example

Unmodified pinned native demo; copy its required local helper files together.

import Pagination from '@mui/material/Pagination';
import Stack from '@mui/material/Stack';

export default function BasicPagination() {
  return (
    <Stack spacing={2}>
      <Pagination count={10} />
      <Pagination count={10} color="primary" />
      <Pagination count={10} color="secondary" />
      <Pagination count={10} disabled />
    </Stack>
  );
}

Example dependency boundaries

@mui/material/Pagination, @mui/material/Stack, @mui/material/PaginationItem, @mui/icons-material/ArrowBack, @mui/icons-material/ArrowForward, react, @mui/material/Typography, @mui/material/usePagination, @mui/material/styles, @mui/material/TablePagination

Direct Icons/System/Utils example imports require their matching 9.4.0 packages. Relative data/helpers are part of the example closure, not extra components. Remote images and simulated operations do not supply a backend.

Pinned upstream API metadata reference

These tables retain the upstream metadata, not a newly inferred generic type system. Conditional generics, inherited props and callback details are defined by the source declarations below. Theme defaults may override metadata defaults.

Pagination

import Pagination from '@mui/material/Pagination';
import { Pagination } from '@mui/material';

PaginationItem

import PaginationItem from '@mui/material/PaginationItem';
import { PaginationItem } from '@mui/material';

Native inheritance: ButtonBase. Parent/DOM props are not fabricated as additional own props.

TablePagination

import TablePagination from '@mui/material/TablePagination';
import { TablePagination } from '@mui/material';

Native inheritance: TableCell. Parent/DOM props are not fabricated as additional own props.

TablePaginationActions

import TablePaginationActions from '@mui/material/TablePaginationActions';
import { TablePaginationActions } from '@mui/material';

Native source declarations

Declarations/imports are extracted from pinned source without flattening unions or external inheritance. Original English comments/types are source reference, not a claim of translated upstream prose. Shared types stay in their native packages.

vendor/src/Pagination/Pagination.d.ts

import * as React from 'react';

import { OverridableStringUnion } from '@mui/types';

import { SxProps } from '@mui/system';

import { Theme } from '../styles';

import { InternalStandardProps as StandardProps } from '../internal';

import { UsePaginationItem, UsePaginationProps } from '../usePagination/usePagination';

import { PaginationClasses } from './paginationClasses';

export interface PaginationRenderItemParams extends UsePaginationItem {
  color: PaginationProps['color'];
  shape: PaginationProps['shape'];
  size: PaginationProps['size'];
  variant: PaginationProps['variant'];
}

export interface PaginationPropsVariantOverrides {}

export interface PaginationPropsSizeOverrides {}

export interface PaginationPropsColorOverrides {}

export interface PaginationProps
  extends
    UsePaginationProps,
    StandardProps<React.HTMLAttributes<HTMLElement>, 'children' | 'onChange'> {
  /**
   * Override or extend the styles applied to the component.
   */
  classes?: Partial<PaginationClasses> | undefined;
  /**
   * The active color.
   * It supports both default and custom theme colors, which can be added as shown in the
   * [palette customization guide](https://mui.com/material-ui/customization/palette/#custom-colors).
   * @default 'standard'
   */
  color?:
    | OverridableStringUnion<'primary' | 'secondary' | 'standard', PaginationPropsColorOverrides>
    | undefined;
  /**
   * Accepts a function which returns a string value that provides a user-friendly name for the current page.
   * This is important for screen reader users.
   *
   * For localization purposes, you can use the provided [translations](https://mui.com/material-ui/guides/localization/).
   * @param {string} type The link or button type to format ('page' | 'first' | 'last' | 'next' | 'previous' | 'start-ellipsis' | 'end-ellipsis'). Defaults to 'page'.
   * @param {number | null} page The page number to format.
   * @param {boolean} selected If true, the current page is selected.
   * @returns {string}
   */
  getItemAriaLabel?:
    | ((
        type: UsePaginationItem['type'],
        page: UsePaginationItem['page'],
        selected: UsePaginationItem['selected'],
      ) => string)
    | undefined;

  /**
   * Render the item.
   * @param {PaginationRenderItemParams} params The props to spread on a PaginationItem.
   * @returns {ReactNode}
   * @default (item) => <PaginationItem {...item} />
   */
  renderItem?: ((params: PaginationRenderItemParams) => React.ReactNode) | undefined;
  /**
   * The shape of the pagination items.
   * @default 'circular'
   */
  shape?: 'circular' | 'rounded' | undefined;
  /**
   * The size of the component.
   * @default 'medium'
   */
  size?:
    OverridableStringUnion<'small' | 'medium' | 'large', PaginationPropsSizeOverrides> | undefined;
  /**
   * The system prop that allows defining system overrides as well as additional CSS styles.
   */
  sx?: SxProps<Theme> | undefined;
  /**
   * The variant to use.
   * @default 'text'
   */
  variant?:
    OverridableStringUnion<'text' | 'outlined', PaginationPropsVariantOverrides> | undefined;
}

export default function Pagination(props: PaginationProps): React.JSX.Element;

vendor/src/PaginationItem/PaginationItem.d.ts

import * as React from 'react';

import { OverridableStringUnion } from '@mui/types';

import { SxProps } from '@mui/system';

import { OverridableComponent, OverrideProps } from '../OverridableComponent';

import { Theme } from '../styles';

import { UsePaginationItem } from '../usePagination/usePagination';

import { PaginationItemClasses } from './paginationItemClasses';

import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';

export interface PaginationItemPropsVariantOverrides {}

export interface PaginationItemPropsSizeOverrides {}

export interface PaginationItemPropsColorOverrides {}

export interface PaginationItemFirstSlotPropsOverrides {}

export interface PaginationItemLastSlotPropsOverrides {}

export interface PaginationItemNextSlotPropsOverrides {}

export interface PaginationItemPreviousSlotPropsOverrides {}

export interface PaginationItemSlots {
  /**
   * The component that renders the first page slot.
   * @default FirstPageIcon
   */
  first: React.ElementType;
  /**
   * The component that renders the last page slot.
   * @default LastPageIcon
   */
  last: React.ElementType;
  /**
   * The component that renders the next page slot.
   * @default NavigateNextIcon
   */
  next: React.ElementType;
  /**
   * The component that renders the previous page slot.
   * @default NavigateBeforeIcon
   */
  previous: React.ElementType;
}

export type PaginationItemSlotsAndSlotProps = CreateSlotsAndSlotProps<
  PaginationItemSlots,
  {
    /**
     * Props forwarded to the first page slot.
     */
    first: SlotProps<
      React.ElementType<React.HTMLProps<HTMLElement>>,
      PaginationItemFirstSlotPropsOverrides,
      PaginationItemOwnerState
    >;
    /**
     * Props forwarded to the last page slot.
     */
    last: SlotProps<
      React.ElementType<React.HTMLProps<HTMLElement>>,
      PaginationItemLastSlotPropsOverrides,
      PaginationItemOwnerState
    >;
    /**
     * Props forwarded to the next page slot.
     */
    next: SlotProps<
      React.ElementType<React.HTMLProps<HTMLElement>>,
      PaginationItemNextSlotPropsOverrides,
      PaginationItemOwnerState
    >;
    /**
     * Props forwarded to the previous page slot.
     */
    previous: SlotProps<
      React.ElementType<React.HTMLProps<HTMLElement>>,
      PaginationItemPreviousSlotPropsOverrides,
      PaginationItemOwnerState
    >;
  }
>;

export interface PaginationItemOwnerState extends PaginationItemProps {}

export interface PaginationItemOwnProps extends PaginationItemSlotsAndSlotProps {
  /**
   * Override or extend the styles applied to the component.
   */
  classes?: Partial<PaginationItemClasses> | undefined;
  /**
   * The active color.
   * It supports both default and custom theme colors, which can be added as shown in the
   * [palette customization guide](https://mui.com/material-ui/customization/palette/#custom-colors).
   * @default 'standard'
   */
  color?:
    | OverridableStringUnion<
        'standard' | 'primary' | 'secondary',
        PaginationItemPropsColorOverrides
      >
    | undefined;
  /**
   * If `true`, the component is disabled.
   * @default false
   */
  disabled?: boolean | undefined;
  /**
   * Whether the custom component should render a native `<button>` element when
   * rendering a React component with the `component` or `slots` prop.
   */
  nativeButton?: boolean | undefined;
  /**
   * The current page number.
   */
  page?: React.ReactNode;
  /**
   * If `true` the pagination item is selected.
   * @default false
   */
  selected?: boolean | undefined;
  /**
   * The shape of the pagination item.
   * @default 'circular'
   */
  shape?: 'circular' | 'rounded' | undefined;
  /**
   * The size of the component.
   * @default 'medium'
   */
  size?:
    | OverridableStringUnion<'small' | 'medium' | 'large', PaginationItemPropsSizeOverrides>
    | undefined;
  /**
   * The system prop that allows defining system overrides as well as additional CSS styles.
   */
  sx?: SxProps<Theme> | undefined;
  /**
   * The type of pagination item.
   * @default 'page'
   */
  type?: UsePaginationItem['type'] | undefined;
  /**
   * The variant to use.
   * @default 'text'
   */
  variant?:
    OverridableStringUnion<'text' | 'outlined', PaginationItemPropsVariantOverrides> | undefined;
}

export interface PaginationItemTypeMap<
  AdditionalProps = {},
  RootComponent extends React.ElementType = 'div',
> {
  props: AdditionalProps & PaginationItemOwnProps;
  defaultComponent: RootComponent;
}

declare const PaginationItem: OverridableComponent<PaginationItemTypeMap>;

export type PaginationItemProps<
  RootComponent extends React.ElementType = PaginationItemTypeMap['defaultComponent'],
  AdditionalProps = {},
> = OverrideProps<PaginationItemTypeMap<AdditionalProps, RootComponent>, RootComponent> & {
  component?: React.ElementType | undefined;
};

vendor/src/TablePagination/TablePagination.d.ts

import * as React from 'react';

import { SxProps } from '@mui/system';

import { Theme } from '../styles';

import { OverridableComponent, OverrideProps } from '../OverridableComponent';

import {
  TablePaginationActionsProps,
  TablePaginationActionsSlots,
} from '../TablePaginationActions';

import { TableCellProps } from '../TableCell';

import { SelectProps } from '../Select';

import { TablePaginationClasses } from './tablePaginationClasses';

import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';

import { ToolbarProps } from '../Toolbar';

import { MenuItemProps } from '../MenuItem';

export interface LabelDisplayedRowsArgs {
  from: number;
  to: number;
  count: number;
  page: number;
}

export interface TablePaginationRootSlotPropsOverrides {}

export interface TablePaginationToolbarSlotPropsOverrides {}

export interface TablePaginationSpacerSlotPropsOverrides {}

export interface TablePaginationSelectLabelSlotPropsOverrides {}

export interface TablePaginationSelectSlotPropsOverrides {}

export interface TablePaginationMenuItemSlotPropsOverrides {}

export interface TablePaginationDisplayedRowsSlotPropsOverrides {}

export interface TablePaginationActionsSlotPropsOverrides {}

export interface TablePaginationSlots {
  /**
   * The component that renders the root slot.
   * [Follow this guide](https://mui.com/material-ui/api/table-cell/#props) to learn more about the requirements for this component.
   * @default TableCell
   */
  root: React.ElementType;
  /**
   * The component that renders the toolbar slot.
   * [Follow this guide](https://mui.com/material-ui/api/toolbar/#props) to learn more about the requirements for this component.
   * @default Toolbar
   */
  toolbar: React.ElementType;
  /**
   * The tag that renders the spacer slot.
   * @default 'div'
   */
  spacer: React.ElementType;
  /**
   * The tag that renders the selectLabel slot.
   * @default 'p'
   */
  selectLabel: React.ElementType;
  /**
   * The component that renders the select slot.
   * [Follow this guide](https://mui.com/material-ui/api/select/#props) to learn more about the requirements for this component.
   * @default Select
   */
  select: React.ElementType;
  /**
   * The component that renders the select slot.
   * [Follow this guide](https://mui.com/material-ui/api/menu-item/#props) to learn more about the requirements for this component.
   * @default MenuItem
   */
  menuItem: React.ElementType;
  /**
   * The tag that renders the displayedRows slot.
   * @default 'p'
   */
  displayedRows: React.ElementType;
  /**
   * The slots that passed to the actions slot.
   */
  actions: TablePaginationActionsSlots;
}

export type TablePaginationSlotsAndSlotProps = CreateSlotsAndSlotProps<
  TablePaginationSlots,
  {
    /**
     * Props forwarded to the root slot.
     * By default, the available props are based on the [TableCell](https://mui.com/material-ui/api/table-cell/#props) component.
     */
    root: SlotProps<
      React.ElementType<TableCellProps>,
      TablePaginationRootSlotPropsOverrides,
      TablePaginationOwnerState
    >;
    /**
     * Props forwarded to the toolbar slot.
     * By default, the available props are based on the [Toolbar](https://mui.com/material-ui/api/toolbar/#props) component.
     */
    toolbar: SlotProps<
      React.ElementType<ToolbarProps>,
      TablePaginationToolbarSlotPropsOverrides,
      TablePaginationOwnerState
    >;
    /**
     * Props forwarded to the spacer slot.
     * By default, the available props are based on the div element.
     */
    spacer: SlotProps<'div', TablePaginationSpacerSlotPropsOverrides, TablePaginationOwnerState>;
    /**
     * Props forwarded to the selectLabel slot.
     * By default, the available props are based on the paragraph element.
     */
    selectLabel: SlotProps<
      'p',
      TablePaginationSelectLabelSlotPropsOverrides,
      TablePaginationOwnerState
    >;
    /**
     * Props forwarded to the select slot.
     * By default, the available props are based on the [Select](https://mui.com/material-ui/api/select/#props) component.
     */
    select: Partial<SelectProps> & TablePaginationSelectSlotPropsOverrides;
    /**
     * Props forwarded to the menuItem slot.
     * By default, the available props are based on the [MenuItem](https://mui.com/material-ui/api/menu-item/#props) component.
     */
    menuItem: SlotProps<
      React.ElementType<MenuItemProps>,
      TablePaginationMenuItemSlotPropsOverrides,
      TablePaginationOwnerState
    >;
    /**
     * Props forwarded to the displayedRows slot.
     * By default, the available props are based on the paragraph element.
     */
    displayedRows: SlotProps<
      'p',
      TablePaginationDisplayedRowsSlotPropsOverrides,
      TablePaginationOwnerState
    >;
    /**
     * Props forwarded to the actions slot.
     */
    actions: TablePaginationActionsProps['slotProps'] & TablePaginationActionsSlotPropsOverrides;
  }
>;

export type TablePaginationBaseProps = Omit<TableCellProps, 'classes' | 'component' | 'children'>;

export interface TablePaginationOwnProps extends TablePaginationBaseProps {
  /**
   * The component used for displaying the actions.
   * Either a string to use a HTML element or a component.
   * @default TablePaginationActions
   */
  ActionsComponent?: React.ElementType<TablePaginationActionsProps> | undefined;
  /**
   * Override or extend the styles applied to the component.
   */
  classes?: Partial<TablePaginationClasses> | undefined;
  /**
   * The total number of rows.
   *
   * To enable server side pagination for an unknown number of items, provide -1.
   */
  count: number;
  /**
   * If `true`, the component is disabled.
   * @default false
   */
  disabled?: boolean | undefined;
  /**
   * Accepts a function which returns a string value that provides a user-friendly name for the current page.
   * This is important for screen reader users.
   *
   * For localization purposes, you can use the provided [translations](https://mui.com/material-ui/guides/localization/).
   * @param {string} type The link or button type to format ('first' | 'last' | 'next' | 'previous').
   * @returns {string}
   * @default function defaultGetAriaLabel(type) {
   *   return `Go to ${type} page`;
   * }
   */
  getItemAriaLabel?: ((type: 'first' | 'last' | 'next' | 'previous') => string) | undefined;
  /**
   * Customize the displayed rows label. Invoked with a `{ from, to, count, page }`
   * object.
   *
   * For localization purposes, you can use the provided [translations](https://mui.com/material-ui/guides/localization/).
   * @default function defaultLabelDisplayedRows({ from, to, count }) {
   *   return `${formatNumber(from)}–${formatNumber(to)} of ${count !== -1 ? formatNumber(count) : `more than ${formatNumber(to)}`}`;
   * }
   */
  labelDisplayedRows?: ((paginationInfo: LabelDisplayedRowsArgs) => React.ReactNode) | undefined;
  /**
   * Customize the rows per page label.
   *
   * For localization purposes, you can use the provided [translations](https://mui.com/material-ui/guides/localization/).
   * @default 'Rows per page:'
   */
  labelRowsPerPage?: React.ReactNode;
  /**
   * Callback fired when the page is changed.
   *
   * @param {React.MouseEvent<HTMLButtonElement> | null} event The event source of the callback.
   * @param {number} page The page selected.
   */
  onPageChange: (event: React.MouseEvent<HTMLButtonElement> | null, page: number) => void;
  /**
   * Callback fired when the number of rows per page is changed.
   *
   * @param {React.ChangeEvent<HTMLTextAreaElement | HTMLInputElement>} event The event source of the callback.
   */
  onRowsPerPageChange?:
    React.ChangeEventHandler<HTMLTextAreaElement | HTMLInputElement> | undefined;
  /**
   * The zero-based index of the current page.
   */
  page: number;
  /**
   * The number of rows per page.
   *
   * Set -1 to display all the rows.
   */
  rowsPerPage: number;
  /**
   * Customizes the options of the rows per page select field. If less than two options are
   * available, no select field will be displayed.
   * Use -1 for the value with a custom label to show all the rows.
   * @default [10, 25, 50, 100]
   */
  rowsPerPageOptions?: ReadonlyArray<number | { value: number; label: string }> | undefined;
  /**
   * If `true`, show the first-page button.
   * @default false
   */
  showFirstButton?: boolean | undefined;
  /**
   * If `true`, show the last-page button.
   * @default false
   */
  showLastButton?: boolean | undefined;
  /**
   * The system prop that allows defining system overrides as well as additional CSS styles.
   */
  sx?: SxProps<Theme> | undefined;
}

export interface TablePaginationOwnerState extends TablePaginationOwnProps {}

export interface TablePaginationTypeMap<AdditionalProps, RootComponent extends React.ElementType> {
  props: AdditionalProps & TablePaginationOwnProps & TablePaginationSlotsAndSlotProps;
  defaultComponent: RootComponent;
}

declare const TablePagination: OverridableComponent<
  TablePaginationTypeMap<{}, React.JSXElementConstructor<TablePaginationBaseProps>>
>;

export type TablePaginationProps<
  RootComponent extends React.ElementType = React.JSXElementConstructor<TablePaginationBaseProps>,
  AdditionalProps = {},
> = OverrideProps<TablePaginationTypeMap<AdditionalProps, RootComponent>, RootComponent> & {
  component?: React.ElementType | undefined;
};

vendor/src/TablePaginationActions/TablePaginationActions.d.ts

import * as React from 'react';

import { IconButtonProps } from '../IconButton/IconButton';

import { SvgIconProps } from '../SvgIcon';

export interface TablePaginationActionsProps extends React.HTMLAttributes<HTMLDivElement> {
  /**
   * Override or extend the styles applied to the component.
   */
  classes?: {} | undefined;
  className?: string | undefined;
  count: number;
  /**
   * If `true`, the component is disabled.
   * @default false
   */
  disabled?: boolean | undefined;
  /**
   * Accepts a function which returns a string value that provides a user-friendly name for the current page.
   * This is important for screen reader users.
   *
   * For localization purposes, you can use the provided [translations](https://mui.com/material-ui/guides/localization/).
   * @param {string} type The link or button type to format ('first' | 'last' | 'next' | 'previous').
   * @returns {string}
   */
  getItemAriaLabel: (type: 'first' | 'last' | 'next' | 'previous') => string;
  onPageChange: (event: React.MouseEvent<HTMLButtonElement> | null, page: number) => void;
  page: number;
  rowsPerPage: number;
  showFirstButton: boolean;
  showLastButton: boolean;
  slotProps?:
    | {
        firstButton?: Partial<IconButtonProps> | undefined;
        lastButton?: Partial<IconButtonProps> | undefined;
        nextButton?: Partial<IconButtonProps> | undefined;
        previousButton?: Partial<IconButtonProps> | undefined;
        firstButtonIcon?: Partial<SvgIconProps> | undefined;
        lastButtonIcon?: Partial<SvgIconProps> | undefined;
        nextButtonIcon?: Partial<SvgIconProps> | undefined;
        previousButtonIcon?: Partial<SvgIconProps> | undefined;
      }
    | undefined;
  slots?: TablePaginationActionsSlots | undefined;
}

export interface TablePaginationActionsSlots {
  /**
   * The component that renders the first button.
   * @default IconButton
   */
  firstButton?: React.ElementType | undefined;
  /**
   * The component that renders the last button.
   * @default IconButton
   */
  lastButton?: React.ElementType | undefined;
  /**
   * The component that renders the next button.
   * @default IconButton
   */
  nextButton?: React.ElementType | undefined;
  /**
   * The component that renders the previous button.
   * @default IconButton
   */
  previousButton?: React.ElementType | undefined;
  /**
   * The component that renders the first button icon.
   * @default FirstPageIcon
   */
  firstButtonIcon?: React.ElementType | undefined;
  /**
   * The component that renders the last button icon.
   * @default LastPageIcon
   */
  lastButtonIcon?: React.ElementType | undefined;
  /**
   * The component that renders the next button icon.
   * @default KeyboardArrowRight
   */
  nextButtonIcon?: React.ElementType | undefined;
  /**
   * The component that renders the previous button icon.
   * @default KeyboardArrowLeft
   */
  previousButtonIcon?: React.ElementType | undefined;
}

declare const TablePaginationActions: React.JSXElementConstructor<TablePaginationActionsProps>;

Post-install acceptance

Run strict types, production build and real interactions. Check keyboard labels/focus, disabled/error/read-only semantics where natively supported, both themes, narrow screens and reduced motion. Verify callbacks against the real host data; do not declare installation complete from copying a prompt. Initialization fixtures also require server HTML and warning-free hydration.

Source and license

https://github.com/mui/material-ui/tree/809a7717b4c050ba3f69b75300689f07c050a16e

MIT · @mui/material@9.4.0. Vendor originals and license are preserved. Full original upstream prose remains in vendor/docs and is not represented as fully translated.