The Legacy Sass API is deprecated and will be removed from the Grid in a future major release. The new API has been designed to be easy to upgrade to - it supports almost the same set of properties as the old API, with a few minor differences documented below.
If you created an app on v27 or earlier and have not updated your import paths, you will be using the Legacy Sass API even if you upgraded your ag-Grid dependency to v28. You can recognise Legacy Sass API import paths because they will have /dist/
or /src/
in them, e.g. @import "ag-grid-community/src/styles/ag-grid.scss"
.
Follow the instructions in this document to upgrade.
If you need to make changes to an app that is still using the legacy API, you can consult the Archived Documentation for the Legacy API.
In addition to the benefits fo the new CSS Variable-driven styling system, the new Sass API provides some benefits:
In order to upgrade, you need to:
grid-styles
mixin instead of the ag-theme-themename
mixin// Legacy API
@import "~ag-grid-community/src/styles/ag-grid.scss";
@import "~ag-grid-community/src/styles/ag-theme-alpine/sass/ag-theme-alpine-mixin.scss";
.ag-theme-alpine {
@include ag-theme-alpine((
alpine-active-color: red
));
.ag-header-cell {
font-style: italic;
}
}
// NOTE: Depending on how you have configured your Sass build the import paths may be
// prefixed with `@`, `~`, or a relative path to `node_modules`. Keep the same style
// of import. The above path is a sass-loader path (`~` prefix), so we edit it to:
// New API
@use "~ag-grid-community/styles" as ag;
// ^^^ Update the import path. Note that `@import` has changed to `@use {path} as {name}`
@include ag.grid-styles((
// ^^^ Include ag.grid-styles which it is no longer nested in .ag-theme-{name} {}
theme: alpine,
// ^^^ Add the theme name to the mixin
alpine-active-color: red,
// ^^^ Pass the same parameters. The new API validates parameters so you will be
// notified if any of the names or values you pass are not valid for the new API
));
.ag-theme-alpine {
.ag-header-cell {
font-style: italic;
}
}
// ^^^ put any custom CSS rules below the grid-styles mixin, wrapped in the theme class
In the above example the Alpine theme is modified but not renamed. If you have renamed the theme, use the new extend-theme
parameter:
// Renaming Alpine ag-theme-custom-name in the Legacy API
.ag-theme-custom-name {
@include ag-theme-alpine((
alpine-active-color: red
));
.ag-header-cell {
font-style: italic;
}
}
// Renaming Alpine to ag-theme-custom-name in the new API
@include ag.grid-styles((
theme: custom-name,
extend-theme: alpine,
alpine-active-color: red,
));
.ag-theme-custom-name {
.ag-header-cell {
font-style: italic;
}
}
// ^^^ put any custom CSS rules below the grid-styles mixin, wrapped in the theme class
If you are using grid Modules you will need to add the @ag-grid-community/styles
module to your dependencies and alter the import paths as follows.
// Legacy API
@import "~@ag-grid-community/core/dist/styles/ag-grid.scss";
// New API
@use "~@ag-grid-community/styles" as ag;
We have tried to make the new Sass Styling API as backwards-compatible as possible, but there are a few breaking changes:
The backwards-compatibility layer introduced in v23 (released 2020) for the benefit of applications written for v22 and below has been removed. This is necessary in order to prepare for the upcoming release of Sass in late 2022 which will remove support for global variables. In practice, this means that if your application was initially created before March 2020 and you are still using the v22 method of configuring themes (setting global variables like $ag-foreground-color: red;
) then you will need to switch to using the map-based configuration API that is shared by both the Legacy Sass API and the new Sass Styling API.
borders-side-button
used to both add a border to the side buttons (vertical tabs), and set the background color when the tab was selected. Now it only sets the border. Use side-button-selected-background-color
to set the background color.
Removed full-width-tabs
. This caused the tabs to expand to fill the space available and was used by the Material theme. If you need the same effect, use CSS:
.your-theme .ag-tab {
flex: 1 1 auto;
}
Removed ag-param($param)
, a Sass function that was replaced at compile time with the value of $param
. All theme variables are now dynamic. Use var
instead:
// old way:
.my-element {
color: ag-param(foreground-color);
}
// new way:
.my-element {
color: var(--ag-foreground-color);
// ^^^ note the --ag- prefix
}
Removed ag-color-property()
, a Sass mixin that outputted a CSS variables with a fallback for IE11. It is no longer required now that IE11 is not a supported browser. Use var
instead:
// old way
.my-element {
@include ag-color-property(color, header-foreground-color);
}
// new way
.my-element {
color: var(--ag-header-foreground-color);
}
Removed %ag-text-input
, a Sass placeholder selector for styling text inputs, is now a mixin:
// old way
%ag-text-input {
color: #999;
}
// new way
@include ag.text-input {
color: #999;
}