Pagination

Pagination is optional and can be enabled by passing a pagination prop to the Grid component.

Two modes are available, controlled and uncontrolled.

In a manner similar to controlled form components in the official React documentation, the parent component can use pagination with react-bootstrap-data-grid in controlled manner by supplying relevant state values and setter functions. This mode allows the parent component full access to the pagination state of the grid, but requires more code to set up than when using uncontrolled mode.

In uncontrolled mode, the parent component specifies the starting state of pagination for the grid, while the grid keeps track of state changes. Note that the starting state is only read once, when the Grid component is mounted. If this behavior is not acceptable, one can either force a remount of the Grid component (e.g. by changing the key prop), or by using controlled mode instead.

Type Definitions

GridPaginationState

This is the type of the pagination prop passed to the Grid component to enable pagination.

It is a discriminated union between ControlledPaginationModel and UncontrolledPaginationModel, which enable controlled and uncontrolled pagination modes for a grid, respectively, when passed as the pagination prop.

This name is legacy name that is preserved to maintain backwards compatibility. It will be renamed to PaginationModel in a future release to be more in line with more recent naming conventions.

ControlledPaginationModel and UncontrolledPaginationModel share the following fields:

Property name	Type definition	Required/Optional	Description
pageSizeOptions	number[]	Optional	List of options for the number of rows to display per page. The Grid component will list the options in a dropdown menu that the user can use to adjust the setting. If this property is not specified, it defaults to `[10, 25, 100]`.
maxPageButtons	number	Optional	The maximum number of buttons associated with numerical page indices to display on the pagination component. For example, if the page size is 10 and there are 50 rows of data, there are 5 total pages of data. The Grid could potentially display a button for each of these 5 pages. If one were to set a `maxPageButtons` setting that is smaller than the total number of pages, such as 3, then only that many buttons will displayed. Note that this setting has no effect on whether to display the buttons that point to the first, last, next, and previous pages. These buttons are always displayed if appropriate. If this property is not specified, it defaults to `5`.
componentSize	"small" \| "medium" \| "large"	Optional	Size of the pagination component based on CSS classes provided by Bootstrap. Set `small` for `pagination-sm` or `large` for `pagination-lg`. Set `medium` or do not set the property for no additional CSS class, which will result in size between that of the `pagination-sm` and `pagination-lg` sizes.
pageSelectorAriaLabel	string	Optional	The `aria-label` attribute of the nav element of the Bootstrap pagination component.
pageSelectorJustifyContent	"start" \| "end" \| "center" \| "between" \| "around" \| "evenly"	Optional	Applies the flexbox justify-content utility to ul element of the Bootstrap pagination component to align the pagination links in the enclosing nav element. See the examples on the Bootstrap documentation site.

ControlledPaginationModel

The member of the discriminated union GridPaginationState that enables controlled pagination mode for a grid. In addition to the properties in the table below, ControlledPaginationModel also includes the properties common with UncontrolledPaginationModel. Those common properties can be found in the GridPaginationState section.

Property name	Type definition	Required/Optional	Description
type	'controlled'	Optional	Discriminator field between `ControlledPaginationModel` and `UncontrolledPaginationModel`. This field is marked optional for backwards compatibility.
pageSizeIndex	number[]	Required	The currently selected page size option based on the index of the array `pageSizeOptions`. For example, if `pageSizeOptions` is `[5, 10, 25]` and `pageSizeIndex` is `0`, the page size would be 5.
setPageSizeIndex	(index: number) => void	Required	Callback function to set the page size index. When the user selects an option in the dropdown menu for selecting page sizes, the Grid component will call this function.
pageNum	number	Required	The (one-based) current page number to be displayed on the grid. For example, if the page size is 10 and there are 30 rows in the grid, a `pageNum` of 1 would have the grid display the first 10 rows of data. Note that it is possible for this number is be out-of-bounds if, for example, enough rows are deleted from the grid that the current page number exceeds the number of pages in total. In that case, the grid will display no rows until enough rows are added back to make the page number within bounds again or when the user chooses a different page with the UI. To avoid this out-of-bounds issue, the parent component may be programmed to be aware of changes to the number of rows and adjust the page number accordingly.
setPageNum	(index: number) => void	Required	Callback function to set the current page of data to display. When the user interacts with the pagination component to select a new page, the Grid component will call this function.

UncontrolledPaginationModel

The member of the discriminated union GridPaginationState that enables uncontrolled pagination mode for a grid. In addition to the properties in the table below, ControlledPaginationModel also includes the properties common with UncontrolledPaginationModel. Those common properties can be found in the GridPaginationState section.

Property name Type definition Required/Optional Description

type

'uncontrolled'

Required

Property name	Type definition	Required/Optional	Description
type	'uncontrolled'	Required	Discriminator field that indicates that this object is of type`UncontrolledPaginationModel` rather than `ControlledPaginationModel`.
startingPageSizeIndex	number	Optional	The initial choice of page size. It is the zero-based index of the array of `pageSizeOptions`. If this property is omitted, it defaults to `0`. This property is read only once, when the `Grid` component mounts. Subsequent changes are ignored unless the `Grid`remounts.
startingCurrentPage	number	Optional	The initial page to be displayed, analogous to the `pageNum` property in `ControlledPaginationModel`. This property is read only once, when the `Grid` component mounts. Subsequent changes are ignored unless the `Grid`remounts.

Discriminator field that indicates that this object is of typeUncontrolledPaginationModel rather than ControlledPaginationModel.

startingPageSizeIndex

number

Optional

The initial choice of page size. It is the zero-based index of the array of pageSizeOptions. If this property is omitted, it defaults to 0.

This property is read only once, when the Grid component mounts. Subsequent changes are ignored unless the Gridremounts.

startingCurrentPage

number

Optional

The initial page to be displayed, analogous to the pageNum property in ControlledPaginationModel.

This property is read only once, when the Grid component mounts. Subsequent changes are ignored unless the Gridremounts.

Examples

Both examples use the sample data from the following file:

paginatedGridData.ts

import { ColDef, RowDef } from "@absreim/react-bootstrap-data-grid";
 
export const cols: ColDef[] = [
  {
    type: "string",
    name: "name",
    label: "Name",
  },
  {
    type: "number",
    name: "class",
    label: "Armor Class",
  },
  {
    type: "string",
    name: "weight",
    label: "Weight",
  },
];
 
interface Data {
  name: string;
  class: number;
  weight: string;
}
 
export const rows: RowDef<Data>[] = [
  {
    id: 0,
    data: {
      name: "Leather Armor",
      class: 11,
      weight: "Light",
    },
  },
  {
    id: 1,
    data: {
      name: "Padded Armor",
      class: 11,
      weight: "Light",
    },
  },
  {
    id: 2,
    data: {
      name: "Studded Leather Armor",
      class: 12,
      weight: "Light",
    },
  },
  {
    id: 3,
    data: {
      name: "Hide Armor",
      class: 12,
      weight: "Medium",
    },
  },
  {
    id: 4,
    data: {
      name: "Chain Shirt",
      class: 13,
      weight: "Medium",
    },
  },
  {
    id: 5,
    data: {
      name: "Scale Mail",
      class: 14,
      weight: "Medium",
    },
  },
  {
    id: 6,
    data: {
      name: "Breastplate",
      class: 14,
      weight: "Medium",
    },
  },
  {
    id: 7,
    data: {
      name: "Half Plate",
      class: 15,
      weight: "Medium",
    },
  },
  {
    id: 8,
    data: {
      name: "Ring Mail",
      class: 14,
      weight: "Heavy",
    },
  },
  {
    id: 9,
    data: {
      name: "Chain Mail",
      class: 16,
      weight: "Heavy",
    },
  },
  {
    id: 10,
    data: {
      name: "Splint Armor",
      class: 17,
      weight: "Heavy",
    },
  },
  {
    id: 11,
    data: {
      name: "Plate Armor",
      class: 18,
      weight: "Heavy",
    },
  },
];

Controlled

Code

ControlledPaginatedGrid.tsx

"use client";
 
import Grid, { GridPaginationState } from "@absreim/react-bootstrap-data-grid";
import { FC, useState } from "react";
import { cols, rows } from "@/assets/pagination/paginatedGridData";
 
const ControlledPaginatedGrid: FC = () => {
  const [pageSizeIndex, setPageSizeIndex] = useState(0);
  const [pageNum, setPageNum] = useState(1);
 
  const paginationState: GridPaginationState = {
    pageSizeOptions: [5, 10, 15],
    pageSizeIndex: pageSizeIndex,
    setPageSizeIndex: (pageSizeIndex) => setPageSizeIndex(pageSizeIndex),
    currentPage: pageNum,
    setCurrentPage: (pageNum) => setPageNum(pageNum),
    maxPageButtons: 5,
    componentSize: "large",
  };
 
  return <Grid rows={rows} cols={cols} pagination={paginationState} />;
};
 
export default ControlledPaginatedGrid;

Live Demo

Name	Armor Class	Weight
Leather Armor	11	Light
Padded Armor	11	Light
Studded Leather Armor	12	Light
Hide Armor	12	Medium
Chain Shirt	13	Medium

Uncontrolled

Code

UncontrolledPaginatedGrid.tsx

"use client";
 
import Grid, {
  UncontrolledPaginationModel,
} from "@absreim/react-bootstrap-data-grid";
import { FC } from "react";
import { cols, rows } from "@/assets/pagination/paginatedGridData";
 
const UncontrolledPaginatedGrid: FC = () => {
  const paginationState: UncontrolledPaginationModel = {
    type: "uncontrolled",
    pageSizeOptions: [5, 10, 15],
  };
 
  return <Grid rows={rows} cols={cols} pagination={paginationState} />;
};
 
export default UncontrolledPaginatedGrid;

Live Demo

Name	Armor Class	Weight
Leather Armor	11	Light
Padded Armor	11	Light
Studded Leather Armor	12	Light
Hide Armor	12	Medium
Chain Shirt	13	Medium