# List and Pagination Controls

Source: https://payloadcms.com/docs/beta/ui-components/list-and-pagination-controls

Payload's list controls support paginated data, page-size selection, sorting, and row selection. Use standalone controls for custom data views and provider-backed controls when extending an existing Admin list.

## Import

Inside a Payload Admin Panel Custom Component:

```tsx
import {
  Pagination,
  PerPage,
  SelectAll,
  SelectMany,
  SelectRow,
  SortColumn,
  SortHeader,
  SortRow,
} from '@payloadcms/ui'
```

## Pagination

**Implementation**

```tsx
const [page, setPage] = useState(4)
const totalPages = 12

<Pagination
  hasNextPage={page < totalPages}
  hasPrevPage={page > 1}
  nextPage={page + 1}
  onChange={setPage}
  page={page}
  prevPage={page - 1}
  totalPages={totalPages}
/>
```

**Styling**

Override field and surface tokens on Pagination to customize its page input without changing other Admin controls.

```css
@layer payload {
  .paginator {
    --field-color-border: #8f87bd;
    --color-border-selected: #6d5dfc;
    --color-bg-secondary: #f8f7fc;
  }
}
```

- `--field-color-border`: Page input border.
- `--color-border-selected`: Page input border while focused.
- `--color-bg-secondary`: Page input background.

`Pagination` is controlled. It renders previous and next controls alongside an editable page input. Pass the current page metadata and update your query or local state from `onChange`.

The input accepts a page between `1` and `totalPages`. Press <kbd>Enter</kbd> or move focus away to apply the value, and press <kbd>Escape</kbd> to restore the current page.

## Page size

`PerPage` displays a compact selector for the number of rows shown on each page.

```tsx
const [limit, setLimit] = useState(10)

<PerPage handleChange={setLimit} limit={limit} limits={[10, 25, 50, 100]} />
```

Reset the current page when changing the limit if the new page size would make that page invalid.

## Sorting

- `SortColumn` renders ascending and descending controls for a named column.
- `SortHeader` switches an orderable list to its configured order field.
- `SortRow` renders the drag handle used by an actively orderable list.

These controls read and update Payload's `ListQuery` context. Use them inside an Admin list or a custom view that provides the same list-query state.

## Selection

- `SelectAll` toggles selection for the current list.
- `SelectRow` toggles one row and respects document locking.
- `SelectMany` renders an action pill for the current selection.

Selection controls require Payload's selection context. `SelectRow` also reads the authenticated user to determine whether a locked row can be selected.

## Common props

These are the props most commonly used. See the exported types in `@payloadcms/ui` for the complete list.

### Pagination props

| Prop          | Type                     | Default | Description                                     |
| ------------- | ------------------------ | ------- | ----------------------------------------------- |
| `page`        | `number`                 | `1`     | Sets the current page.                          |
| `totalPages`  | `number`                 | `1`     | Sets the total page count.                      |
| `hasNextPage` | `boolean`                | `false` | Enables the next-page control.                  |
| `hasPrevPage` | `boolean`                | `false` | Enables the previous-page control.              |
| `nextPage`    | `number`                 | —       | Sets the page selected by the next control.     |
| `prevPage`    | `number`                 | —       | Sets the page selected by the previous control. |
| `onChange`    | `(page: number) => void` | —       | Runs when the user selects a different page.    |

### PerPage props

| Prop           | Type                      | Default | Description                                      |
| -------------- | ------------------------- | ------- | ------------------------------------------------ |
| `limit` \*     | `number`                  | —       | Sets the selected page size.                     |
| `limits` \*    | `number[]`                | —       | Sets the available page sizes.                   |
| `defaultLimit` | `number`                  | `10`    | Provides a fallback when `limit` is not numeric. |
| `handleChange` | `(limit: number) => void` | —       | Runs when the user chooses a new page size.      |

_\* An asterisk denotes that a prop is required._

## Internal list wrappers

`PageControls` and `PageControlsComponent` are exported for Payload's own list views but are marked internal. For Custom Components, compose `Pagination` and `PerPage` unless you are intentionally extending Payload's existing list-query implementation.