JavaScript Data GridUpgrading to AG Grid 33

What's New

See the release post for details of what's new in version 33.

Codemods

Follow these steps to upgrade your project's AG Grid version to 33.0.0:

1. Locate your project's package.json and note the version of AG Grid that you are currently using.

2. Update any AG Grid dependencies listed in the package.json to version 33.0.0.

3. Open a terminal and navigate to your project's root folder.

4. Run the migrate command of version 33.0 of the AG Grid codemod runner, where $FROM_VERSION refers to your project's existing AG Grid version:

   npx @ag-grid-devtools/cli@33.0 migrate --from=$FROM_VERSION
   

   This will update your project's source files to prepare for the new release.

   By default the Codemod runner will locate all source files within the current directory. For projects with more specific requirements, pass a list of input files to the migrate command, or specify the --help argument to see more fine-grained usage instructions.

The codemod only transforms source files that make use of deprecated features, so if you aren't currently making use of any of those APIs your source code will be unaffected by the codemod.

See the Codemods documentation for more details.

Changes to Modules

Version 33 introduces a major change to how modules work to allow for smaller bundle sizes. Previously AG Grid supported two versions - modules and packages. These have now been merged together to allow for both a simpler configuration and greater optimisation of bundle size.

If you are using the UMD bundle, then you do not need to make any changes as all modules are automatically registered. Otherwise, see the steps below.

Migrating from Packages

If you were previously using packages (e.g. ag-grid-community), you now need to register the feature modules that you are using in the grid.

The simplest way to do this is to use one of the bundles to register all the features:

• AllCommunityModule for AG Grid Community.
• AllEnterpriseModule for AG Grid Enterprise. (*)

This can then be passed to the module registry, e.g. ModuleRegistry.registerModules([AllCommunityModule]).

(*) If you are using the enterprise features Integrated Charts or Sparklines, then you need to provide the relevant module from AG Charts to AllEnterpriseModule. Use the Module Selector tool to help generate the correct registration code.

If you want to optimise your bundle size, you can register only the modules that you are using.

See the Modules page for help on selecting modules, as well as more information on how to register modules (including registering different modules for different grid instances).

Migrating from Modules

All NPM packages for the modules version of AG Grid (e.g. @ag-grid-community/core) have been replaced as below:

• All @ag-grid-community/* packages are replaced with ag-grid-community. (*)
• All @ag-grid-enterprise/* packages are replaced with ag-grid-enterprise.

(*) Note that @ag-grid-community/locale remains unchanged.

Additionally, many features have been removed from the core module into their own modules, and some modules have been split into smaller modules.

You can use the Module Selector tool to work out which modules you require.

To help identify missing modules, we recommend including the ValidationModule in your development build. This will provide details on which module is missing for a particular feature.

The core community module has been split into many modules. See the Module Selector for the full list of new modules.

The following changes have been made to existing modules:

• GridChartsModule - This has been replaced with IntegratedChartsModule. This additionally needs to be passed the relevant module from AG Charts, e.g. IntegratedChartsModule.with(AgChartsEnterpriseModule). Use the Module Selector tool to help generate the correct registration code.
• SparklinesModule - This needs to be passed the relevant module from AG Charts, e.g. SparklinesModule.with(AgChartsCommunityModule). Use the Module Selector tool to help generate the correct registration code.
• ColumnsToolPanelModule - This no longer imports the RowGroupingModule by default.
• ExcelExportModule - This no longer imports the CsvExportModule by default.
• MenuModule - This has been split into ColumnMenuModule for the Column Menu, and ContextMenuModule for the Context Menu.
• RangeSelectionModule - This has been replaced with CellSelectionModule.
• RowGroupingModule - This has been split into several modules. RowGroupingModule now only contains Row Grouping. Tree Data uses TreeDataModule, Pivoting uses PivotModule, the Row Grouping Panel / Pivot Panel uses RowGroupingPanelModule, and the Group Filter uses GroupFilterModule.

Deprecations

Modules

• ModuleRegistry.register(module) - deprecated, use ModuleRegistry.registerModules([module]) instead.
• MenuModule - deprecated, use ColumnMenuModule for the Column Menu and/or ContextMenuModule for the Context Menu instead.
• RangeSelectionModule - deprecated, use CellSelectionModule instead.

Column Object

• Column.isHovered() - deprecated, use api.isColumnHovered(column) instead.

Grid API

• deselectAllFiltered - deprecated, use deselectAll('filtered') instead.
• deselectAllOnCurrentPage - deprecated, use deselectAll('currentPage') instead.
• selectAllFiltered - deprecated, use selectAll('filtered') instead.
• selectAllOnCurrentPage - deprecated, use selectAll('currentPage') instead.

Grid Options

• cellRendererParams.checkbox - deprecated, use rowSelection.checkboxLocation = "autoGroupColumn" instead.
• gridOptions.sortingOrder - deprecated, use defaultColDef.sortingOrder instead.
• gridOptions.unSortIcon - deprecated, use defaultColDef.unSortIcon instead.
• groupRemoveLowestSingleChildren - deprecated, use groupHideParentOfSingleChild: 'leafGroupsOnly' instead.
• groupRemoveSingleChildren - deprecated, use groupHideParentOfSingleChild: true instead.
• suppressMakeColumnVisibleAfterUnGroup - deprecated, use suppressGroupChangesColumnVisibility: "suppressShowOnUngroup" instead.
• suppressPropertyNamesCheck - deprecated without replacement. Previously used for adding user properties in gridOptions and columnDefs. Now, use the context property in both for storing arbitrary metadata.
• suppressRowGroupHidesColumns - deprecated, use suppressGroupChangesColumnVisibility: "suppressHideOnGroup" instead.
• When setting both suppressMakeColumnVisibleAfterUnGroup and suppressRowGroupHidesColumns to true, use suppressGroupChangesColumnVisibility: true instead.

Row Node

• childIndex - deprecated, use rowNode.parent?.childrenAfterSort?.findIndex(r => r === rowNode) instead.
• firstChild - deprecated, use rowNode.parent?.childrenAfterSort?.[0] === rowNode instead.
• lastChild - deprecated, use !!rowNode.parent?.childrenAfterSort && (rowNode.parent.childrenAfterSort[rowNode.parent.childrenAfterSort.length - 1] === rowNode) instead.

Row Node Events

• childIndexChanged - deprecated, use the global modelUpdated event to determine when row children have changed.
• firstChildChanged - deprecated, use the global modelUpdated event to determine when row children have changed.
• lastChildChanged - deprecated, use the global modelUpdated event to determine when row children have changed.

Theming Custom Icons

• smallDown - deprecated, use:
  • advancedFilterBuilderSelect for Advanced Filter Builder dropdown.
  • selectOpen for Select cell editor and dropdowns (e.g., Integrated Charts menu).
  • richSelectOpen for Rich Select cell editor.
• smallLeft - deprecated, use:
  • panelDelimiterRtl for Row Group Panel / Pivot Panel.
  • subMenuOpenRtl for sub-menus.
• smallRight - deprecated, use:
  • panelDelimiter for Row Group Panel / Pivot Panel.
  • subMenuOpen for sub-menus.

Breaking Changes

This release includes the following breaking changes:

Packaging

ag-grid-enterprise no longer includes ag-charts-community as a dependency. Also, the package ag-grid-charts-enterprise is no longer published.

For Integrated Charts and Sparklines, the application must now explicitly include either ag-charts-community or ag-charts-enterprise in its package.json and register the module AgChartsCommunityModule or AgChartsEnterpriseModule as follows:

The GridChartsModule has been replaced by the IntegratedChartsModule.

import { AgChartsEnterpriseModule } from 'ag-charts-enterprise';
import { ModuleRegistry } from 'ag-grid-community';
import { IntegratedChartsModule } from 'ag-grid-enterprise';

ModuleRegistry.registerModules([
    IntegratedChartsModule.with(AgChartsEnterpriseModule),
    // sparklines
    SparklinesModule.with(AgChartsEnterpriseModule)
]);

Property Value Coercion

For non-TS users and users who use TS but avoid type validation there's changes in property value coercion:

For boolean values provided as strings, “false” is no longer converted to false anymore - all string values are truthy.

Theming

The Theming API is now the default theming method of the grid. Because of this, setting the theme via a theme class (class="ag-theme-quartz") on the parent element of the grid is no longer supported. Applications using CSS file-based themes must either pass a theme object to the theme grid option or the string "legacy" to keep using class name-based themes. This is documented in the Theming API Migration Guide.

Setting any of the custom icons listed below will have the provided custom icon only apply in the specific use case its name indicates, instead of all cases as before. To have the custom icon apply to additional cases, set the additional icon keys pointing to the same custom icon. See list of icons changed:

• smallDown (deprecated):

  • advancedFilterBuilderSelect for Advanced Filter Builder dropdown
  • selectOpen for Select cell editor and dropdowns (e.g., Integrated Charts menu)
  • richSelectOpen for Rich Select cell editor

• smallLeft (deprecated):

  • panelDelimiterRtl for Row Group Panel / Pivot Panel
  • subMenuOpenRtl for sub-menus

• smallRight (deprecated):

  • panelDelimiter for Row Group Panel / Pivot Panel
  • subMenuOpen for sub-menus

• previous:

  • previous for pagination
  • chartsThemePrevious for Integrated Charts theme picker

• next:

  • next for pagination
  • chartsThemeNext for Integrated Charts theme picker

• cancel:

  • cancel for column drag pills
  • richSelectRemove for Rich Select cell editor pills

• menu:

  • menu for button to launch the legacy column menu
  • legacyMenu for legacy column menu tab header

• menuAlt:

  • menuAlt for new column menu
  • chartsMenu for Integrated Charts menu

• columns:

  • columns for the column menu/column chooser
  • columnsToolPanel for the Columns Tool Panel tab icon

• filter:

  • filter for buttons that open the filter (header/menu)
  • filtersToolPanel for the Filters Tool Panel tab icon
  • filterActive for displaying the filter is active (header with legacy column menu, Filters Tool Panel item)
  • filterTab for the filter tab of the legacy tabbed column menu

• save:

  • save for the export menu
  • chartsDownload for Integrated Charts download

• columnSelectClosed:

  • columnSelectClosed for the Columns Tool Panel/Column Chooser/column tab in the legacy tabbed column menu
  • accordionClosed for accordions (Filters Tool Panel, Integrated Charts tool panels)

• columnSelectOpen:

  • columnSelectOpen for the Columns Tool Panel/Column Chooser/column tab in the legacy tabbed column menu
  • accordionOpen for accordions (Filters Tool Panel, Integrated Charts tool panels)

• columnSelectIndeterminate:

  • columnSelectIndeterminate for the Columns Tool Panel/Column Chooser/column tab in the legacy tabbed column menu
  • accordionIndeterminate for accordions (Filters Tool Panel, Integrated Charts tool panels)

Server-side Rendering

AG Grid no longer patches global properties that are not present in a Server environment, i.e HTMLElement and others. If possible you should avoid rendering AG Grid on the server as this is not supported.

Typing

• The types for the grid options getMainMenuItems and getContextMenuItems, as well as the column definition properties mainMenuItems and contextMenuItems, have changed. Instead of string values in the arrays (and in defaultItems in the callback), this is now typed to DefaultMenuItem which only allows the available menu values.
• The type for the grid option chartMenuItems has changed. Instead of string values in the array (and in defaultItems in the callback), this is now typed to ChartDefaultMenuItem which only allows the available values.
• The column property is now optional in the callback to get column menu items (in the grid option getMainMenuItems or colDef.mainMenuItems). column will be null when a column group header or empty column space is right-clicked on. A new property columnGroup will be provided when a column group header is right-clicked on.

Integrated Charts

navigator is removed from ChartFormatPanelGroup. Navigator setting is now part of the Integrated Charts Advanced Settings.

Modules

api.getRowDropZoneParams() returns undefined if the RowDragModule is not registered.

Server-side Row Model

Server-side Row Model full store (activated by suppressServerSideInfiniteScroll property) is now removed. Please use the standard server-side row model functionality as documented.

Floating Filters

Floating filters provided via the colDef.filter values text, number, date, set, multi, and group no longer work. Use the values agTextColumnFilter, agNumberColumnFilter, agDateColumnFilter, agSetColumnFilter, agMultiColumnFilter, and agGroupColumnFilter instead.

Column State

Column state properties in the column definition are no longer parsed to number/boolean. Provide the correct types instead of strings.

Grid State

Grid state colId ag-Grid-ControlsColumn is now named ag-Grid-SelectionColumn. Restoring grid state with the old colId will have no effect.

Sparklines

• type: 'column' - removed, use type: 'bar' and direction: 'vertical' instead.
• tooltip.renderer no longer returns tooltip font colour and opacity - use CSS instead.
• tooltip.xOffset / tooltip.yOffset - removed, use CSS instead.
• tooltip.container - removed, AG Charts now handles this.
• marker.formatter - removed, use marker.itemStyler instead.
• sparklineOptions.[line, area, bar, column] to apply styles - removed, use sparklineOptions properties instead.
• highlightStyle now follows the AG Charts options - for more customisation options use an itemStyler instead.
• sparklineOptions.valueAxisDomain - removed, use sparklineOptions.min/max instead.
• sparklineOptions.paddingInner / sparklineOptions.paddingOuter - removed, use sparklineOptions.axis.paddingInner / sparklineOptions.axis.paddingOuter instead.
• sparklineOptions.container - removed.
• sparklineOptions.label.placement - updated to use AG Charts Label Placement. Instead of insideBase, center, insideEnd and outsideEnd, please use inside-center, inside-start, inside-end or outside-end

Grid API

• new Grid() - removed, use createGrid instead.
• api - no longer mutated onto the provided gridOptions for Javascript users.
• First argument of selectAll and deselectAll grid API methods is now the selection mode, the event source is now the second argument. Both are optional.
• getFirstDisplayedRow - removed, use getFirstDisplayedRowIndex instead.
• getLastDisplayedRow - removed, use getLastDisplayedRowIndex instead.
• getModel() - removed, use the appropriate grid API methods instead.
• getValue - removed, use getCellValue instead.
• showColumnMenuAfterButtonClick - removed, use IHeaderParams.showColumnMenu within a header component, or api.showColumnMenu elsewhere.
• showColumnMenuAfterMouseClick - removed, use IHeaderParams.showColumnMenuAfterMouseClick within a header component, or api.showColumnMenu elsewhere.
• autoSizeColumn(key) - removed, please use autoSizeColumns([colKey]) instead.
• setColumnWidths(key, newWidth) - removed, please use setColumnWidths([{key: newWidth}]) instead.
• moveColumn(key, toIndex) - removed, please use moveColumns([key], toIndex) instead.
• addAggFunc(key, func) - removed, please use addAggFuncs({ key: func }) instead.
• removeValueColumn(colKey) - removed, please use removeValueColumns([colKey]) instead.
• addValueColumn(colKey) - removed, please use addValueColumns([colKey]) instead.
• removeRowGroupColumn(colKey) - removed, please use removeRowGroupColumns([colKey]) instead.
• addRowGroupColumn(colKey) - removed, please use addRowGroupColumns([colKey]) instead.
• removePivotColumn(colKey) - removed, please use removePivotColumns([colKey]) instead.
• addPivotColumn(colKey) - removed, please use addPivotColumns([colKey]) instead.
• setColumnVisible(key, visible) - removed, please use setColumnsVisible([key], visible) instead.
• setColumnPinned(key, pinned) - removed, please use setColumnsPinned([key], pinned) instead.
• To get/set individual filter models, use getColumnFilterModel or setColumnFilterModel instead.

Grid Options

• suppressServerSideInfiniteScroll - removed without replacement.
• Interface getServerSideGroupLevelParams - suppressInfiniteScroll property removed without replacement.
• advancedFilterModel - removed, please use initialState.filter.advancedFilterModel instead.
• suppressAsyncEvents - removed, Events should be handled asynchronously.
• cellFlashDelay - removed, please use cellFlashDuration instead.
• cellFadeDelay - removed, please use cellFadeDuration instead.
• Use enableCellChangeFlash in the ColDef or defaultColDef for all columns.
• suppressGroupMaintainValueType - removed.
• groupIncludeFooter - removed, please use groupTotalRow instead.
• groupIncludeTotalFooter - removed, please use grandTotalRow instead.
• suppressServerSideInfiniteScroll - removed.
• serverSideSortOnServer - removed.
• serverSideFilterOnServer - removed.
• tabToNextCell returning null - removed.
• tabToNextHeader returning null - removed.

ColDef

• suppressCellFlash - removed, please use enableCellChangeFlash={false} in the ColDef.
• columnsMenuParams - removed, please use columnChooserParams instead.
• suppressMenu - removed, please use suppressHeaderMenuButton instead.

Interfaces

• RowDragEvent interface: vDirection property is now typed as 'up' | 'down' | null.
• IFloatingFilterParams: suppressFilterButton - removed, please use colDef.suppressFloatingFilterButton instead.
• ITextFilterParams: textCustomComparator - removed, please use textMatcher instead.
• IFloatingFilter: onParamsUpdated - removed, please use refresh instead.
• IFilterParams: valueGetter - removed, please use getValue instead.
• IDate: onParamsUpdated - removed, please use refresh instead.
• IGroupCellRendererParams: footerValueGetter - removed, please use totalValueGetter instead.
• FlashCellsParams:
  • flashDelay - removed, please use flashDuration instead.
  • fadeDelay - removed, please use fadeDuration instead.
• ToolPanelColumnCompParams: ToolPanelColumnCompParams - removed, please use IToolPanelColumnCompParams instead.
• ExcelAlignment: Legacy property verticalText - removed.
• ExcelFont: Legacy property charSet - removed.
• ExcelStyle: Legacy property name - removed.

Changes List

If you would like to see the full list of changes in this release, please see the Changelog.