Introduction
Basic Usage
Sorting
Pagination
Filtering
Selection
Editing
Styling
Export
Toolbar
Pro Pro
Resize Pro
Reorder Pro
Versions
Migrate to Version 2
Migrate to Version 3

Migrate to Version 3

Version 3 introduces a number of breaking changes. This article describes how to migrate from version 2.x to version 3.0.0.

GridPaginationState Rename

The type GridPaginationState type is type of the pagination prop that is passed to the Grid or GridPro component to enable pagination. It has been renamed to PaginationModel. If any of your existing code is explicitly referring to this type by name, simply rename each occurrence to PaginationModel.

Filtering and Toolbar Changes

Filtering UI Access Change

Previously, there were two ways to access the filtering interface:

  • A button labeled Show Filter Options that is by default located above the main table.
  • A button on the toolbar.

Previously, the developer could choose between these two modes by specifying the useToolbar prop. Now, the useToolbar prop has been removed and the only way to access the filtering UI is via the toolbar.

The toolbar will show up as long as there is at least one feature enabled for a grid that requires the toolbar to access. Filtering is one such feature and can be enabled by supplying a filterModel prop to the Grid or GridPro component.

Toolbar Enablement Change

As mentioned in the previous section, previously, the useToolbar prop must be specified on the Grid or GridPro component for the toolbar to appear. Now, the toolbar appears as long as one feature is enabled for the grid that requires the toolbar to access.

These features are filtering and export. Filtering is enabled by passing a value for the filterModel prop to a Grid or GridPro component. Export is enabled by passing a true value for the allowExport prop.

Export Enablement Change

Previously, export could be enabled by passing a true value for the useToolbar prop.

Now, as described in the previous section, it can instead be enabled by passing a true value for the allowExport prop.

Submit and Cancel Buttons

For both the filtering and export UIs, the Submit button now closes the interface. Previously, the button left the interface open.

Both interfaces now also have a Cancel button that closes the interface without making any changes.

Migration Steps

  • If your app is previously using the old interface to access the filtering UI, instruct your users to use the toolbar instead.
  • If your app was setting the useToolbar set to true to enable the toolbar and exporting, remove the useToolbar prop and instead set allowExport to true to continue enabling exporting.
  • You may with to instruct your users about the changes with the Submit and Cancel buttons, although they are fairly straightforward.

Main Table Responsive by Default

Previously, tables were only responsive if the developer passed the responsive prop to the Grid or GridPro component. The containing div to which Bootstrap's table-responsive utility class was applied also only existed when the table was responsive.

Now, the containing div always exists and tables are responsive by default.

To disable responsive behavior for a table, it is necessary to use the styling customization feature to remove the table-responsive class from the div that contains the main table. Setting the value of the additionalComponentsStyleModel.tableDiv property of the styleModel prop to [] will bring back the original behavior. There is a difference that in version 2.x, the containing div didn't exist at all if the responsive prop was set to false or not set.

Migration Steps

  • If you were using the responsive prop before, remove it.
  • If you want to disable responsive behavior for the main table, do so by configuring the styleModel prop using the instructions above.

Style Model Behavior Changes

Baseline Bootstrap Classes

Previously, there were certain "baseline" Bootstrap classes that were preserved even if one were to pass in a property to the style model for that element. These classes were:

  • table for the main table
  • btn for buttons
  • form-control for text, number, or date inputs
  • form-select for select dropdown controls

These baseline classes are no longer preserved when an array is passed. For example, one could previously make a table striped by passing in the value ["table-striped"] to the mainTableStyleModel.table property. The table element would then have the classes table and table-striped.

Now, to achieve the same effect, one needs to pass in ["table", "table-striped"].

Migration Steps

For grids for which you were previously applying custom styling to one of the affected elements, modify the values for these properties to include the baseline classes as well.

For style model properties of type string[], simply add in the baseline class: ["btn", "btn-info"] rather than ["btn-info"].

For style model properties that are functions, have the function return the baseline class as well. For example, if one wanted to make form controls small, instead of

() => ["form-control-sm"]

include the baseline form-control class in the function's return value:

() => ["form-control", "form-control-sm"]

For a list of all affected properties, see the Properties Affected section below.

Empty Array vs Falsy Values

Previously, the grid did not differentiate between empty arrays ([]) and undefined when passed as the value for a style model property.

For style model properties of type string[], if an empty array [] were specified, the grid would use the default styles.

Similarly, for style model properties that are functions, for the elements where the function returns [], the grid uses default styles for that particular element.

Now, if [] is specified for a style model property, or when the function specified for a style model property returns [], the grid will remove the default styles for the affected elements.

Array-typed Style Model Properties

For example, the main table element has the Bootstrap table CSS class by default. The mainTableStyleModel.table style model property can be used to customize the styling for this element. The type of this property is string[].

Specifying [] for the property will remove the table class.

Specifying undefined or omitting the property entirely will cause the grid to behave in the original way by applying default styling.

Function-typed Style Model Properties

Previously, the return type for all function-typed style model properties was string[]. Now, due to this change in behavior, the return type has been changed to string[] | null. Whenever a function returns null for a particular element, the grid will use default classes for that element.

For example, to make all cell editing input fields smaller via the form-control-sm class except the first, one can use the following function for the mainTableStyleModel.tbodyTdInput property.

(_, displayRowIndex) => {
    if (displayRowIndex === 0) {
        return null;
    }
 
    return ["form-control", "form-control-sm"];
}

Migration Steps

Migration is only needed if the developer was previously using empty string arrays for styleModel properties or having function passed as a styleModel property return an empty string array. Migration steps differ based on whether a styleModel prop is a string array or a function.

  • For properties that are string arrays, wherever a styleModel property was previously passed an empty array, simply pass undefined or omit the property.
  • For styleModel properties that are functions, modify the function to return null where the function was previously returning an empty array.

Properties Affected

Below is a complete list of existing properties of the styleModel prop that are affected by these changes.

PropertyTypeDefault ClassesPreviously Customizable Defaults
mainTableStyleModel.tablestring[]["table"](none)
mainTableStyleModel.tbodyTdInput(rowId: RowId, displayRowIndex: number, colIndex: number) => string[] | null["form-control"](none)
mainTableStyleModel.editCancelButton(rowId: RowId, displayIndex: number) => string[] | null["btn", "btn-secondary"]["btn-secondary"]
mainTableStyleModel.editSaveButton(rowId: RowId, displayIndex: number) => string[] | null["btn", "btn-primary"]["btn-primary"]
mainTableStyleModel.editDeleteButton(rowId: RowId, displayIndex: number) => string[] | null["btn", "btn-secondary"]["btn-secondary"]
mainTableStyleModel.editStartButton(rowId: RowId, displayIndex: number) => string[] | null["btn", "btn-primary"]["btn-primary"]
mainTableStyleModel.rowSelectColThstring[]["btn-primary"](none)
filterInputTableStyleModel.startDateInput(rowIndex: number) => string[] | null["form-control"](none)
filterInputTableStyleModel.endDateInput(rowIndex: number) => string[] | null["form-control"](none)
filterInputTableStyleModel.submitButtonstring[]["btn", "btn-primary"]["btn-primary"]
filterInputTableStyleModel.schemeSelectionInput(rowIndex: number) => string[] | null["form-select"](none)
filterInputTableStyleModel.numberInput(rowIndex: number) => string[] | null["form-control"](none)
filterInputTableStyleModel.searchStringInput(rowIndex: number) => string[] | null["form-control"](none)

New and Removed Style Model Properties

All changes to the Style Model occur in the additionalComponentsStyleModel property.

Removed Properties

The following properties have been removed. Both of the below properties belong to the original way of accessing the filter options table. Since the toolbar is now the only way of accessing the filter options table, the style model properties related to the original way are no longer applicable.

  • filterInputsDiv
  • filterUiToggleButton

Migration Steps

Omit these properties from a styleModel prop if they were being previously used.

Added Property

As mentioned before, the main table is now responsive by default. To make a table responsive, one must contain the table element in a div element and apply CSS to the div. The following attribute allows the developer to specify custom classes for the div.

  • tableDiv

Also as mentioned before, this div has the table-responsive Bootstrap utility class by default that makes the table responsive. The developer can remove this class from the div by specifying an array containing any number of class strings.