Pagination in Apex Grid
The Apex grid supports both local and remote pagination. In local mode, the grid slices the data array internally. In remote mode, the grid emits paging events but does not slice: the consumer supplies the current page in response to pageChanged.
Pagination renders an <apex-grid-paginator> element below the data area, with CSS parts for every control.
Enabling pagination
grid.pagination = {
enabled: true,
pageSize: 25,
pageSizeOptions: [10, 25, 50, 100],
};
Configuration
interface PaginationConfiguration {
enabled?: boolean;
mode?: 'local' | 'remote';
page?: number;
pageSize?: number;
pageSizeOptions?: number[];
totalItems?: number;
paginator?: 'compact' | 'full';
}
- mode switches between local slicing (default) and remote mode. In remote mode you are responsible for replacing the
dataarray in response topageChanged. - page is the starting page, zero-based (default
0). - pageSize is the rows-per-page count (default
25). - pageSizeOptions populates the page-size dropdown in the paginator UI (default
[10, 25, 50, 100]). ApageSizemissing from the list is added to the dropdown and selected. - totalItems is, in remote mode, the number of rows the server holds for the current filter, so the paginator can count the pages. Ignored in local mode, where the grid counts the rows itself.
- paginator picks the layout (default
'full', see Compact paginator).
Rows pinned to the top or bottom show on every page, so they do not count toward the pages.
Properties
const page = grid.page; // current page (zero-based)
const pageSize = grid.pageSize;
const pageCount = grid.pageCount;
const total = grid.totalItems; // rows the pager pages through
const slice = grid.pageItems; // rows visible on the current page
totalItems is the post-filter, post-sort row count. With pagination it leaves out pinned rows, and in remote mode it is the pagination.totalItems you supplied. page and pageSize can also be assigned, which navigates like gotoPage() and setPageSize().
Programmatic API
await grid.gotoPage(2); // zero-based: the third page
await grid.setPageSize(50);
await grid.nextPage();
await grid.previousPage();
await grid.firstPage();
await grid.lastPage();
Each resolves to true when the change was applied, or false when it was cancelled or changed nothing. Out-of-range pages are clamped.
Events
- pageChanging: cancellable; fires before the page or page size changes. Detail:
{ page, pageSize, nextPage, nextPageSize }. In remote mode, this is where you trigger your data fetch and callevent.preventDefault()if the fetch fails. - pageChanged: fires after the change is applied. Detail:
{ page, pageSize, pageCount, totalItems }, the change that was applied, so two quicknextPage()calls report page 2 and then page 3.
A local page or page size change does not rerun sorting, filtering or the rest of the pipeline, so custom dataPipelineConfiguration hooks are not called for it. Remote mode reruns the pipeline. A page change is announced once to screen readers ("Page X of N").
Remote pagination
In remote mode, the grid does not slice. Keep pagination.totalItems at the server-reported row count and replace data with the current page's rows when pageChanged fires:
grid.pagination = { enabled: true, pageSize: 25, mode: 'remote', totalItems: 1234 };
grid.addEventListener('pageChanged', async (e) => {
grid.data = await fetchPage(e.detail.page, e.detail.pageSize);
});
When a server-side filter changes how many rows the server holds, update pagination.totalItems so the page count follows. grid.totalItems is read-only: it reports the value you supplied.
Compact paginator
The full paginator shows the page size select, the "start-end of total" summary, first, previous, "page / count", next and last. In a narrow grid it drops the page size select first, then first and last, so previous and next always stay reachable.
paginator: 'compact' always uses the narrow layout: the summary, previous, "page / count" and next. It suits a small grid such as a dashboard tile:
grid.pagination = { enabled: true, pageSize: 10, paginator: 'compact' };
CSS parts
Style the paginator from outside the grid with apex-grid::part():
paginator-host: the<apex-grid-paginator>elementpaginator: the paginator's containerpaginator-size: the page-size selector wrapperpaginator-info: the "1-25 of 100" summarypaginator-controls: the first / previous / next / last button clusterpaginator-page: the "page / count" labelpaginator-button: each of the first, previous, next and last buttonspaginator-first,paginator-prev,paginator-next,paginator-last: one button each (they also carrypaginator-button)
apex-grid::part(paginator) {
padding-inline: 12px;
}
apex-grid::part(paginator-prev),
apex-grid::part(paginator-next) {
font-weight: 600;
}
The paginator follows --header-background like the rest of the header area, and its text size follows --ag-fs-cell-secondary.