Skip to content
Handsontable dev

Rows pagination

Split large data sets into pages to improve usability and rendering performance. Pagination operates fully on the client side and automatically recomputes the total page count whenever rows are added, removed, filtered, or otherwise modified.

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:

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, horizon and classic themes, aligning them with your app’s design guidelines. For a list of available variables, see the Handsontable Design System on Figma.

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 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.
Handsontable 16.1: Row Pagination, Loading Plugin, and Long-Term Support Policy

Configuration options

pagination
fixedRowsBottom
fixedRowsTop

Hooks

beforePageChange()
afterPageChange()
beforePageSizeChange()
afterPageSizeChange()
afterPageSizeVisibilityChange()
afterPageCounterVisibilityChange()
afterPageNavigationVisibilityChange()

Plugins

Pagination
NestedRows
MergeCells

Result

After completing this guide, your grid divides rows into pages with built-in navigation controls. You can configure the page size, customize the UI position, control pagination programmatically, and react to page changes using hooks.

Troubleshooting

Didn’t find what you need? Try this:

View related topics
Report an issue
Start a discussion
Contact our technical support