OmniGrid | Framework-agnostic data grid

API / Plugins / Base / Pagination

PaginationPlugin

The PaginationPlugin from @omnigrid/pagination-plugin splits rows into pages and renders navigation controls in top / bottom slots. In client mode the plugin slices data locally via a data processor; in server mode it delegates fetching to the host and only manages UI state.

Live demo|NPM

Constructor

new PaginationPlugin<T>(options?: PaginationPluginOptions<T>)

Options

Properties accepted by PaginationPluginOptions<T>.

Property	Description
pageSize numberdefault: 50	Number of rows per page. Set to 0 to fit whole rows into the grid viewport.
pageSizes number[]default: [20, 50, 100]	Numeric page-size choices shown in the selector. A custom positive pageSize is added automatically. When automatic sizing is enabled, an Auto choice is prepended.
mode "client" \| "server"default: "client"	Client mode slices data locally; server mode leaves fetching to the host.
totalRows number	Total dataset size, primarily used to calculate pages in server mode.
initialPage numberdefault: 1	Page to show initially. Page numbers start at 1.
slot PaginationSlotNamedefault: "bottom"	Default slot for blocks that do not specify their own slot.
position SlotPositiondefault: "end"	Default alignment for blocks that do not specify their own position.
priority numberdefault: 0	Default render priority for blocks that do not specify their own priority. Lower values render first.
blocks PaginationBlockOption[]default: ["navigation"]	Visible blocks and their order or individual placement. Available names are rowInfo, pageSize, and navigation.
quickJump booleandefault: false	Show an input for entering a page number in the navigation block.
pageInputCharacters numberdefault: 2	Width of the page-number input in characters when quickJump is enabled.
labels PaginationLabels	Custom accessible labels and pagination text formatters.
icons Partial<Record<PaginationIconName, IconDefinition<T>>>	Custom icon definitions for the first, previous, next, and last controls.

Callbacks

onChange: (params: { page: number; pageSize: number }) => void

Called in server mode when the requested page or page size changes.

Instance methods

getState(): PaginationState

Returns the current page, page size, total rows, and computed total pages.

goToPage(page): void

Navigates to a specific 1-based page number, clamped to the available page range. In server mode, calls onChange when the requested page changes.

nextPage(): void

Advances to the next page.

prevPage(): void

Returns to the previous page.

setPageSize(pageSize): void

Sets the page size and returns to the first page. In server mode, calls onChange. Use 0 only when the plugin was configured with pageSize: 0.

setTotalRows(totalRows): void

Updates the total dataset size, primarily for server-side pagination.

Types and Interfaces

PaginationState

Current pagination values, including the computed number of pages.

interface PaginationState {
    /** The active page number, starting at 1. */
    page: number;
    /** The configured page size, or 0 when automatic sizing is enabled. */
    pageSize: number;
    /** Total number of rows in the dataset. */
    totalRows: number;
    /** Total number of pages, with a minimum of 1. */
    totalPages: number;
}

PaginationLabels

Labels and formatter callbacks used by pagination controls.

interface PaginationLabels {
    /** Accessible label for the first-page control. */
    firstAriaLabel?: string;
    /** Accessible label for the previous-page control. */
    prevAriaLabel?: string;
    /** Accessible label for the next-page control. */
    nextAriaLabel?: string;
    /** Accessible label for the last-page control. */
    lastAriaLabel?: string;
    /** Formats the current page and total page count when quick jump is disabled. */
    pageInfo?: (page: number, totalPages: number) => string;
    /** Formats the visible row range and total row count. */
    rowInfo?: (from: number, to: number, totalRows: number) => string;
    /** Visible label for the page-size selector. */
    pageSizeLabel?: string;
    /** Accessible label for the page-size options menu. */
    pageSizesLabel?: string;
    /** Formats the total page count shown next to the quick-jump input. */
    pageCount?: (totalPages: number) => string;
}

PaginationIconName

Name of one of the four page-navigation icons.

type PaginationIconName = "first" | "prev" | "next" | "last";

PaginationBlockName

Name of a pagination control block.

type PaginationBlockName = "rowInfo" | "pageSize" | "navigation";

PaginationSlotName

Grid slot where pagination controls can be rendered.

type PaginationSlotName = "top" | "bottom";

PaginationBlockConfig

Placement of a pagination block in the grid's top or bottom slot.

type PaginationBlockConfig = Omit<BlockConfig<PaginationBlockName>, "slot"> & {
    slot?: PaginationSlotName;
};

PaginationBlockOption

A pagination block name or its placement configuration.

type PaginationBlockOption = PaginationBlockName | PaginationBlockConfig;