JavaScript Data Gridv32 Themes: Sass Styling API

The Sass Styling API is an optional lightweight wrapper around Themes and Global Style Customisations that automates the process of importing CSS files and setting CSS variables.

The Sass API provides a few benefits on top of the CSS API:

1. Colour blending with older themes. The Sass API saves you the work of defining multiple related colours. For example with the Alpine theme, if you set alpine-active-color to red then row-hover-colour will automatically be set to a light pink. Without Sass, this functionality is only available in the Quartz theme.
2. Validation. In the Sass API you will get a build error if you accidentally pass an invalid parameter name or value. In CSS this would be silent and lead to incorrect styling.
3. Automatic selection of CSS files. The Sass API ensures that only the necessary CSS files are loaded, only once, in the correct order, and combined into a single file.

Getting Started

First, set up your project to compile Sass (.scss) files. We provide examples for the major frameworks:

• Vanilla JS and React: use the Sass CLI or Webpack and sass-loader
• Angular: see our Angular CLI example
• Vue: see our Vue CLI example

Next, import the Sass API in your .scss file:

@use "ag-grid-community/styles" as ag;

The above import path assumes that node_modules is added to the Sass load path. Depending on how your project is configured, you may need to add one or more prefixes to the import path:

• @ag-grid-community/styles if you're using the grid modules feature
• node_modules/ag-grid-community/styles if node_modules is not in the Sass load path
• ~ag-grid-community/styles is you're using webpack and sass-loader (the tilde instructs sass-loader to look in node_modules)

Simple Example

To emit all the styles you need for an AG Grid application, include the grid-styles mixin:

@use "ag-grid-community/styles" as ag;
@include ag.grid-styles();

Because no theme is specified, it will default to Quartz. Compiling this file will select the ag-grid.css and ag-theme-quartz.css files from the grid distribution and combine them into the output. There is no need to separately include ag-grid.css in your build.

To use the theme, set the ag-theme-quartz class on your grid div:

<div id="myGrid" class="ag-theme-quartz">

To customise the theme, you can add more parameters to the grid-styles mixin, as described in the rest of this page.

Choosing a Theme

Use the theme parameter to set the name of the outputted theme.

@use "ag-grid-community/styles" as ag;
@include ag.grid-styles((
    theme: balham
));

This can be either:

1. a provided theme (quartz, quartz-dark, alpine, alpine-dark, balham, balham-dark or material). The CSS file for the theme will automatically be included.
2. Any string of your choice to create a custom theme.

Setting CSS Variables

The Sass Styling API is a wrapper around the CSS variable API for design customisation, you can pass any supported CSS variable as a parameter to the Sass API:

@use "ag-grid-community/styles" as ag;
@include ag.grid-styles((
    theme: balham,
    --ag-balham-active-color: deeppink
));

For information about what CSS variables and rules to use to control grid features, see the full list of CSS variables

The Sass API provides a little bit of sugar to make it easier to read and remember some parameter values and assists migration from the Legacy Sass API.

• The --ag- prefix is optional.
• You can pass true or false to any borders-* parameter to enable or disable the border (true is converted to solid 1px and false to none)
• You can pass true or false to the header-column-separator-display or header-column-resize-handle-display parameters (true is converted to block and false to none)
• You can pass null to any *-color parameter, which will be converted to a CSS value of transparent

Adding Your Own CSS Rules

When you cannot achieve the effect you want with variables, add custom CSS rules below the grid-styles mixin:

@use "ag-grid-community/styles" as ag;
@include ag.grid-styles((
    theme: alpine
));
.ag-theme-quartz {
    // Nest rules in .ag-theme-quartz so that the selectors include the theme name.
    // Without the theme name, your styles will not override the theme's built-in
    // styles due to CSS selector specificity rules.
    .ag-header-cell-label {
        font-style: italic;
    }
}

Multiple Themes

You can use multiple themes. This is useful for projects that allow the end user to select a theme. In simple use cases where each theme has the same configuration you can pass an array of theme names to the themes parameter.

@use "ag-grid-community/styles" as ag;
@include ag.grid-styles((
    themes: (alpine, alpine-dark),
    alpine-active-color: red
));

If each theme needs a different configuration, themes can be a map of theme name to additional configuration:

@use "ag-grid-community/styles" as ag;
@include ag.grid-styles((
    themes: (
        alpine: (
            header-background-color: rgb(234, 191, 177),
        ),
        alpine-dark: (
            header-background-color: rgb(72, 44, 17),
        )
        // ^^^ different header background for each theme
    ),
    alpine-active-color: red
    // ^^^ but the same active colour
));

Suppressing Native Widget Styles

Setting suppress-native-widget-styling to true will suppress native widget styling, see Customising Inputs & Widgets for more information.

Extending a Provided Theme

If you want to use a provided theme (say alpine), apply some customisations, and package this as a custom theme to share between multiple apps, then you may want to use a different theme name.

To do this, set the theme parameter to your custom theme and the extend-theme parameter to one of the provided themes:

@use "ag-grid-community/styles" as ag;
@include ag.grid-styles((
    theme: acmecorp,
    extend-theme: alpine,
    alpine-active-color: red
));

To use this theme, add the ag-theme-acmecorp class to your grid div.

Theme extension is only available in the Sass API. The alternative method of creating a reusable package of design customisations works in both Sass and pure CSS projects.

Theme extension works with multiple themes too, set the extend-theme parameter at the theme level:

@use "ag-grid-community/styles" as ag;
@include ag.grid-styles((
    themes: (
        acmecorp: (extend-theme: alpine),
        acmecorp-dark: (extend-theme: alpine-dark),
    ),
    alpine-active-color: red
));