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:

Pagination

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.

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

PerPage props

* 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.