Unstyled Table Pagination

Table Pagination is an interface tool for splitting up large amounts of data to make it easier for users to navigate.

Introduction

The Unstyled Table Pagination component lets you add pagination controls to a table. It controls two properties of its parent table:

displayed page index
number of rows per page

Table Pagination renders its internal elements in a <td> tag by default so it can be inserted into a table's <tr>. You can use the component or slots.root prop to render a different root element—for example, if you need to place the pagination controls outside of the table. See the Slot props section for details.

Component

Usage

After installation, you can start building with this component using the following basic elements:

import TablePaginationUnstyled from '@mui/base/TablePaginationUnstyled';

export default function MyApp() {
  return (
    <table>
      <tr>
        <TablePaginationUnstyled />
      </tr>
    </table>
  );
}

Basics

The following demo shows an example of customized pagination controls in a table footer that spans the entire row:

Dessert	Calories	Fat
Frozen yoghurt	159	6
Ice cream sandwich	237	9
Eclair	262	16
Cupcake	305	3.7
Marshmallow	318	0
Rows per page: 1–5 of 13

Anatomy

The Unstyled Table Pagination component is composed of a root <td> that houses up to ten interior slots:

toolbar
spacer
selectLabel
selectRoot
select
selectIcon
input
menuItem
displayedRows
actions

<td class="MuiTablePaginationUnstyled-root">
  <div class="MuiTablePaginationUnstyled-toolbar">
    <div class="MuiTablePaginationUnstyled-spacer"></div>
    <p class="MuiTablePaginationUnstyled-selectLabel" id="mui-48">Rows per page:</p>
    <select class="MuiTablePaginationUnstyled-select">
      <option class="MuiTablePaginationUnstyled-menuItem">All</option>
    </select>
    <p class="MuiTablePaginationUnstyled-displayedRows">1–5 of 13</p>
    <div class="MuiTablePaginationUnstyled-actions">
      <button disabled="" aria-label="Go to first page" title="Go to first page">
        <span>|⇽</span>
      </button>
      <button
        disabled=""
        aria-label="Go to previous page"
        title="Go to previous page"
      >
        <span>⇽</span>
      </button>
      <button aria-label="Go to next page" title="Go to next page">
        <span>⇾</span>
      </button>
      <button aria-label="Go to last page" title="Go to last page">
        <span>⇾|</span>
      </button>
    </div>
  </div>
</td>

Slot props

Use the component prop to override the root slot with a custom element:

<TablePaginationUnstyled component="div" />

Use the slots prop to override any interior slots in addition to the root:

<TablePaginationUnstyled slots={{ root: 'div', toolbar: 'nav' }} />

Use the slotProps prop to pass custom props to internal slots. The following code snippet applies a CSS class called my-spacer to the spacer slot:

<TablePaginationUnstyled slotProps={{ spacer: { className: 'my-spacer' } }} />

Customization

Custom pagination options

You can customize the options shown in the Rows per page select using the rowsPerPageOptions prop. This prop requires an array of either numbers or objects:

numbers—each number is used for the option's label and value.
```
<TablePaginationUnstyled rowsPerPageOptions={[10, 50]} />
```
objects—the value and label keys are used, respectively, for the value and label of the option (useful for labels such as All).
```
<TablePaginationUnstyled
  rowsPerPageOptions={[10, 50, { value: -1, label: 'All' }]}
/>
```

Customized look and feel

The following demo shows another example of pagination controls but with additional style customization:

Dessert	Calories	Fat
Frozen yoghurt	159	6
Ice cream sandwich	237	9
Eclair	262	16
Cupcake	305	3.7
Marshmallow	318	0
Rows per page: 1–5 of 13

TablePaginationUnstyled API

Import

import TablePaginationUnstyled from '@mui/base/TablePaginationUnstyled';
// or
import { TablePaginationUnstyled } from '@mui/base';

You can learn about the difference by reading this guide on minimizing bundle size.

Props

Props of the native component are also available.

Name	Type	Default	Description
count^*	number		The total number of rows. To enable server side pagination for an unknown number of items, provide -1.
onPageChange^*	func		Callback fired when the page is changed. Signature: `function(event: React.MouseEvent<HTMLButtonElement> \| null, page: number) => void` event: The event source of the callback. page: The page selected.
page^*	integer		The zero-based index of the current page.
rowsPerPage^*	integer		The number of rows per page. Set -1 to display all the rows.
component	elementType		The component used for the root node. Either a string to use a HTML element or a component.
getItemAriaLabel	func	function defaultGetAriaLabel(type: ItemAriaLabelType) { return `Go to ${type} page`; }	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. Signature: `function(type: string) => string` type: The link or button type to format ('first' \| 'last' \| 'next' \| 'previous').
labelDisplayedRows	func	function defaultLabelDisplayedRows({ from, to, count }: LabelDisplayedRowsArgs) { return `${from}–${to} of ${count !== -1 ? count : `more than ${to}`}`; }	Customize the displayed rows label. Invoked with a `{ from, to, count, page }` object. For localization purposes, you can use the provided translations.
labelId	string		Id of the label element within the pagination.
labelRowsPerPage	node	'Rows per page:'	Customize the rows per page label. For localization purposes, you can use the provided translations.
onRowsPerPageChange	func		Callback fired when the number of rows per page is changed. Signature: `function(event: React.ChangeEvent<HTMLTextAreaElement \| HTMLInputElement>) => void` event: The event source of the callback.
rowsPerPageOptions	Array<number \| { label: string, value: number }>	[10, 25, 50, 100]	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.
selectId	string		Id of the select element within the pagination.
slotProps	{ actions?: func \| object, displayedRows?: func \| object, menuItem?: func \| object, root?: func \| object, select?: func \| object, selectLabel?: func \| object, spacer?: func \| object, toolbar?: func \| object }	{}	The props used for each slot inside the TablePagination.
slots	{ actions?: elementType, displayedRows?: elementType, menuItem?: elementType, root?: elementType, select?: elementType, selectLabel?: elementType, spacer?: elementType, toolbar?: elementType }	{}	The components used for each slot inside the TablePagination. Either a string to use a HTML element or a component. See Slots API below for more details.

The ref is forwarded to the root element.