React Data Grid Rows pagination

React Data GridRows pagination

The pagination component splits the data into a range of pages, allowing users to easily navigate through large data sets.

On this page

Overview

With pagination, large data sets are divided into smaller pages, significantly improving usability and rendering performance. Users can navigate pages using built-in UI controls such as page navigation buttons, a page size selector, and a page counter, or you can manage pages programmatically via Handsontable's API.

Pagination operates fully on the client side, requiring all data to be loaded into Handsontable.

Whenever rows are added, removed, hidden, unhidden, filtered, or otherwise modified, pagination automatically recomputes total pages and adjusts the currently visible slice of data.

By default, the plugin does not override core data access methods (e.g., getData, getData*, getSourceData, getSourceData*, countRows). Instead, a developer must explicitly call the pagination getCurrentPageData method or getPaginationData method conjunction with core methods (e.g., getData) to interact with paged data.

Pagination demo

Use the controls below the grid to switch between pages.

    Enable pagination

    To enable pagination set the pagination option to true.

    const configurationOptions = {
  pagination: true,
};

    Defining the option as true is equivalent to defining the following options:

    const configurationOptions = {
  pagination: {
    pageSize: 10,
    pageSizeList: ['auto', 5, 10, 20, 50, 100],
    initialPage: 1,
    showPageSize: true,
    showCounter: true,
    showNavigation: true,
    uiContainer: null,
  },
};

    Configure pagination

    You can customize pagination using available settings, such as showing or hiding specific UI sections like the page size selector, page counter, or page navigation.

    Control aspects such as the number of rows per page, the initial page on load, or whether the grid should automatically adjust page size based on the container's height.

    You can configure the following options:

    const configurationOptions = {
  pagination: {
    // Set number of rows per page. If the value is `auto` then the page size is calculated
    // based on available height.
    pageSize: 20,
    // Provide a list of selectable page sizes
    pageSizeList: ['auto', 10, 20, 50],
    // Set the initial page when the grid loads
    initialPage: 2,
    // Show or hide the page size section
    showPageSize: false,
    // Show or hide the page counter section
    showCounter: true,
    // Show or hide the page navigation section
    showNavigation: true,
    // Custom container where the pagination UI will be injected (optional)
    uiContainer: null,
  }
};

    In the data grid below, several pagination options are applied to provide a customized experience. The demo allows you to resize the table container and observe how the auto page size feature (pageSize: 'auto') dynamically adjusts the number of visible rows to fit the available space.

      Control pagination programmatically

      Build your own pagination UI using API methods such as setPage(), nextPage(), prevPage(), and more. For a complete list of available methods and hooks, see the Pagination plugin API reference.

        Choose where to display the pagination UI

        By default, the pagination UI is displayed at the bottom of the grid. You can change the place of the pagination component by setting the uiContainer option to a custom container element.

          Modify paged data

          Sometimes you need to modify data only on the currently visible page. Core method like setDataAtCell operates on all rows, including those hidden by pagination. To modify data only on the current page, you can use the getPaginationData method to get the pagination state and use it in conjunction with Core method.

            Use pagination hooks

            You can run your code before or after different stages of pagination, using the following Handsontable hooks:

            <HotTable
  beforePageChange={() => {
    // add your code here
    return false; // to block page change
  }}
  afterPageChange={() => {
    // add your code here
  }}
  beforePageSizeChange={() => {
    // add your code here
    return false; // to block page size change
  }}
  // ...
/>

            Localize pagination

            Translate default pagination labels - such as "Page size:", "Page" and more - using the global translations mechanism. The pagination introduces the following keys to the language dictionary that you can use to translate the pagination UI:

            • PAGINATION_SECTION = 'Pagination'
            • PAGINATION_PAGE_SIZE_SECTION = 'Page size'
            • PAGINATION_PAGE_SIZE_AUTO = 'Auto'
            • PAGINATION_COUNTER_SECTION = '[start] - [end] of [total]'
            • PAGINATION_NAV_SECTION = 'Page [currentPage] of [totalPages]'
            • PAGINATION_FIRST_PAGE = 'Go to first page'
            • PAGINATION_PREV_PAGE = 'Go to previous page'
            • PAGINATION_NEXT_PAGE = 'Go to next page'
            • PAGINATION_LAST_PAGE = 'Go to last page'

            To learn more about the translation mechanism, see the Languages guide.

            The example below demonstrates how to customize the translation of the pagination counter and navigation sections.

              Customize pagination UI

              You can customize the look of each pagination element by assigning new values to the CSS variables defined in our main and horizon themes, aligning them with your app's design guidelines. For a list of available variables, see the Handsontable Design System on Figma or view the theme source files (opens new window) on GitHub.

              Within the plugin the following CSS variables are available:

              • --ht-pagination-bar-foreground-color: Controls the text color of pagination bar elements;
              • --ht-pagination-bar-background-color: Sets the background color of the pagination bar;
              • --ht-pagination-bar-horizontal-padding: Defines the left and right padding of the pagination bar;
              • --ht-pagination-bar-vertical-padding: Controls the top and bottom padding of the pagination bar;

              Importing the pagination module

              You can reduce the size of your bundle by importing and using only the modules that you need.

              To use pagination, you need only the following modules:

              // import the base module
import Handsontable from 'handsontable/base';

// import Handsontable's CSS
import 'handsontable/styles/handsontable.css';
import 'handsontable/styles/ht-theme-main.css';

// import the Pagination plugin
import { registerPlugin, Pagination } from 'handsontable/plugins';

// register the Pagination plugin
registerPlugin(Pagination);

              Known limitations

              When pagination is enabled:

              • fixedRowsTop and fixedRowsBottom options should be disabled.
              • NestedRows and MergeCells plugins should be disabled.
              • The height option set as auto is not supported when the pageSize: 'auto' is set.
              • Pagination always displays a fixed number of rows per page (default is 10), regardless of data changes such as hiding, trimming, filtering, removing, adding, or pasting rows - unless pageSize: 'auto' is set.

              Troubleshooting

              Didn't find what you need? Try this: