Search

JavaScript Data GridMigrating to the Theming API

Migrating to the Theming API

Before v32.2, themes were imported as CSS files in our NPM modules. For the purposes of this guide we'll call those the legacy themes. This guide covers migrating from legacy themes to the Theming API.

If your application is split between multiple pages, it can be migrated one page at a time. However a single document can not contain both legacy styling and the Theming API, because the two styles conflict with each other.

Understanding the scope of the Theming API

When migrating an app from legacy styles to the Theming API, it is useful to know:

  • The DOM structure of the grid, and class names used, does not change when using the Theming API. Any custom CSS you have written that targets ag-* class names work without modification.
  • Many custom properties have been renamed, see below for the full list. If you make extensive use of --ag-* custom properties, updating these will be the majority of the work in migrating to the Theming API.
  • In the legacy themes, custom properties had to be set in CSS. When migrating custom properties to the Theming API you may choose whether to specify them in JavaScript in order to get Typescript validation of property names and values, or to continue to set them in CSS. The list below provides the JS API names, to convert them to CSS use kebab-case and add the --ag- prefix (tooltipTextColor -> --ag-tooltip-text-color).

1. Remove legacy CSS imports

Applications import the legacy CSS files either through JS (import 'ag-grid-community/styles/ag-grid.css';) or by copying the CSS files from the NPM package to the application. Any such CSS imports should be removed.

2. Convert any css custom properties you are using to the new names

Key changes

  • --ag-grid-size -> --ag-spacing spacing works a little bit differently from the old "grid size". It controls the padding around elements, whereas grid size controlled their size. So setting spacing to 0 will result in a grid with no padding, whereas setting grid size to 0 would have resulted in zero-height rows.
  • --ag-active-color, --ag-alpine-active-color, --ag-balham-active-color, --ag-material-accent-color -> use accentColor
  • --ag-borders* -> there has been a reworking of border parameters, see the Theming API docs for the new list of border parameters.
  • --ag-row-border-color, --ag-row-border-style, --ag-row-border-width -> replaced with rowBorder
  • --ag-icon-font-* -> The Theming API uses SVG icons instead of icon fonts. We intend to add icon font support in a future version of the Theming API, for now either continue to use the legacy styles, or write your own CSS rules to insert your custom icon font into our icons.
  • --ag-icon-image-* -> The theming API currently does not provide variables to individually replace SVG icons. For now, use CSS rules instead.

Properties with a direct replacement

While developing the Theming API we took the opportunity to rename many of our parameters to use a consistent naming scheme and semantics.

  • --ag-secondary-border-color -> there is no longer a concept of "secondary" borders use borderColor or CSS rules to target specific borders
  • --ag-secondary-foreground-color -> chromeBackgroundColor
  • --ag-selected-tab-underline-color -> tabSelectedUnderlineColor
  • --ag-selected-tab-underline-transition-speed -> tabSelectedUnderlineTransitionDuration
  • --ag-selected-tab-underline-width -> tabSelectedUnderlineWidth
  • --ag-advanced-filter-column-pill-color -> --ag-advanced-filter-builder-column-pill-color
  • --ag-advanced-filter-join-pill-color -> --ag-advanced-filter-builder-join-pill-color
  • --ag-advanced-filter-option-pill-color -> --ag-advanced-filter-builder-option-pill-color
  • --ag-advanced-filter-value-pill-color -> --ag-advanced-filter-builder-value-pill-color
  • --ag-borders-input -> inputBorder
  • --ag-borders-input-invalid -> inputInvalidBorder
  • --ag-card-radius -> borderRadius
  • --ag-card-shadow -> Use one of the more specific shadow parameters introduced in the Theming API
  • --ag-cell-horizontal-border -> columnBorder
  • --ag-checkbox-* -> there has been a significant overhaul of checkbox parameters giving greater control over the appearance of checkboxes. See the Theming API docs.
  • --ag-chip-background-color -> columnDropCellBackgroundColor
  • --ag-chip-border-color -> columnDropCellBorder
  • --ag-control-panel-background-color -> chromeBackgroundColor
  • --ag-data-color -> chromeBackgroundColor
  • --ag-header-column-resize-handle-display
  • --ag-header-column-separator-color, --ag-header-column-separator-width, --ag-header-column-separator-display -> headerColumnBorder
  • --ag-header-column-separator-height -> headerColumnBorderHeight
  • --ag-header-foreground-color -> headerTextColor
  • --ag-input-border-color -> inputBorder
  • --ag-input-border-color-invalid -> inputInvalidBorder
  • --ag-input-disabled-border-color -> inputDisabledBorder
  • --ag-input-focus-border-color -> inputFocusBorder
  • --ag-input-focus-box-shadow -> inputFocusShadow
  • --ag-menu-border-color -> menuBorderColor
  • --ag-panel-border-color -> dialogBorder
  • --ag-quartz-icon-active-color -> this was used to apply an outline to focussed icons, now all focussed elements throughout the grid use focusShadow
  • --ag-quartz-icon-hover-color -> iconButtonHoverColor

Properties removed with no replacement, use CSS rules to achieve the same effect

These properties were either outdated, confusing to use, or provided no benefit over using CSS rules.

  • --ag-borders-side-button
  • --ag-tab-min-width
  • --ag-menu-min-width
  • --ag-subheader-toolbar-background-color
  • --ag-subheader-background-color
  • --ag-side-button-selected-background-color
  • --ag-spectrum-alpha-background-checked
  • --ag-chart-menu-pill-select-button-color
  • --ag-disabled-foreground-color
  • --ag-filter-tool-panel-sub-level-row-height
  • --ag-minichart-selected-chart-color
  • --ag-minichart-selected-page-color

3. [optional] Remove ag-theme-* classes and update CSS rules that target them

Legacy themes were applied by adding a class name e.g. ag-theme-quartz to the wrapper element of the grid. Any CSS custom rules had to include this class name in order to override the styles defined in the theme. This is no longer required, but still works. You may take the opportunity to simplify your styles:

/* Required in legacy CSS themes, still works with Theming API */
.ag-theme-quartz {
    --ag-foreground-color: red;
}
.ag-theme-quartz .ag-header-cell {
    font-style: italic;
}

/* Valid in Theming API only: */
body {
    /* set vars on `body` to affect all grids on the page regardless of the theme they
       use. You can also use a different selector to affect only specific grids. */
    --ag-foreground-color: red;
}
.ag-header-cell {
    font-style: italic;
}