AG Grid 33.0 significantly reduces bundle size via modularization and enhances functionality, theming and accessibility as described in the release post. These major improvements require certain breaking changes as listed below.
Please use the codemods to start your migration, then review the changes to modules and themes.
AG Grid 33.0 is aimed at addressing long-standing community feedback around bundle size and theming. Naturally, given the significance of these changes, AG Grid 33.0 has introduced more breaking changes than usual. We recognise that not all users can immediately benefit from these improvements.
Therefore we are launching Long-Term Support (LTS) versions of AG Grid (v32-lts) and AG Charts (v10-lts), ensuring you can continue receiving bug fixes without upgrading to the latest major release. We will proactively identify necessary fixes, but please feel free to report any issues you encounter against our LTS versions.
Version 33.0 introduces a major change in how feature modules are set up to reduce the bundle size. Previously there were two separate ways to include AG Grid in your project - via AG Grid Modules or AG Grid Packages. These have now been unified to simplify configuration whilst also introducing more fine-grained modules to reduce bundle size.
To take full advantage of the new modules, use the Module Selector to work out which modules you require for the AG Grid features you need.
In previous versions separate npm packages were required to achieve tree shaking of grid features to reduce the bundle size. The improvements made in version 33.0 remove the need for separate npm packages to achieve tree shaking.
As a result all feature modules have been collapsed into either ag-grid-community or ag-grid-enterprise and all @ag-grid-community/** and @ag-grid-enterprise/** npm packages are removed as of version 33.0.
The changes can be summarised as follows:
@ag-grid-community/vue3 is replaced with ag-grid-vue3
All individual @ag-grid-community/** packages are replaced by a single tree-shakable package ag-grid-community
Exception - the @ag-grid-community/locale package remains unchanged.
All individual @ag-grid-enterprise/** packages are replaced by a single tree-shakable package ag-grid-enterprise.
Here is an example of a typical package.json diff for the migration:
The codemod for version 33.0 will automatically update all your import paths and module registration to ensure backwards compatibility.
After updating your package.json file, we recommend using the Codmod to assist your migration as it will update all your applications import paths and module registration to ensure backwards compatibility.
GridChartsModule - replaced with IntegratedChartsModule and requires AG Charts module to be registered
SparklinesModule - requires AG Charts module to be registered
The codemod will include the new modules to match the existing behaviour of v32 module dependencies. For example, if you were importing the ExcelExportModule in v32 then the codemod will automatically include the CsvExportModule in v33.
To help identify configuration issues we strongly recommend including the ValidationModule in your development build. This module enables AG Grid to validate your configuration and provide extended error diagnosis to help you resolve issues quickly.
Ensure you’re not including the ValidationModule in your production build to avoid increasing bundle size unnecessarily. Note if you are using either AllCommunityModule or AllEnterpriseModule it is included by default.
If you are currently using AG Grid packages, which did not support tree shaking, then you can match the existing behaviour by registering either AllCommunityModule or AllEnterpriseModule via the ModuleRegistry before any grid is created.
Using the AllCommunityModule / AllEnterpriseModule will prevent tree shaking. In order to reduce the bundle size, use the Module Selector to only register the modules you require instead of all modules.
Most users will also want to set { theme: "legacy" } if not already using the new Theming Api. See Theming for more details.
AG Grid Community
import{ AllCommunityModule, ModuleRegistry, provideGlobalGridOptions }from'ag-grid-community';// Register all community features
ModuleRegistry.registerModules([AllCommunityModule]);// Mark all grids as using legacy themesprovideGlobalGridOptions({theme:"legacy"});
AG Grid Enterprise
import{ ModuleRegistry, provideGlobalGridOptions }from'ag-grid-community';import{ AllEnterpriseModule, LicenseManager }from'ag-grid-enterprise';
LicenseManager.setLicenseKey('your License Key');// Register all enterprise features
ModuleRegistry.registerModules([AllEnterpriseModule]);// Mark all grids as using legacy themesprovideGlobalGridOptions({theme:"legacy"});
AG Grid Enterprise no longer includes AG Charts as part of its distribution to avoid bloating the bundle size. If you are using either Integrated Charts or Sparklines, you must now explicitly include either the community / enterprise AG Charts library as a dependency.
For an application using Integrated Charts / Sparklines via the AllEnterpriseModule bundle with the Enterprise version of AG Charts first add ag-charts-enterprise to your package.json dependencies.
If you are using AG Grid Modules instead of AllCommunityModule or AllEnterpriseModule, then both the IntegratedChartsModule and SparklinesModule also require the AG Charts module to be registered when they are used.
The new and improved Theming API is now the default theming method for AG Grid. If you wish to migrate to the Theming Api see the Theming API Migration Guide. However, this is not a requirement to upgrade to version 33.0.
If you want to upgrade to version 33.0 without immediately adopting the Theming API, you can opt back in to the v32 style of themes by setting the grid option theme: "legacy". You can then continue to use legacy themes.
If you have multiple grids you can mark them all as using legacy themes via a Global Grid Option. Enterprise users can define this alongside their license key.
import{ provideGlobalGridOptions }from'ag-grid-community';// Mark all grids as using legacy themesprovideGlobalGridOptions({theme:"legacy"});
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 runner will check the state of your project to ensure that you don't lose any work. If you would rather see a diff of the changes instead of applying them, pass the --dry-run argument.
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.
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.
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-cpcked on. A new property columnGroup will be provided when a column group header is right-clicked on.
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
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)
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.
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.
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.