---
title: "Legacy Themes: Sass Styling API"
framework: angular
version: "36.1.0"
---

# Legacy Themes: Sass Styling API

The Sass Styling API is an optional lightweight wrapper around [Themes](https://www.ag-grid.com/angular-data-grid/themes/) and [Global Style Customisations](https://www.ag-grid.com/angular-data-grid/theming-v32-customisation/) that automates the process of importing CSS files and setting CSS variables.

> **Note**
>
> This page describes the grid's legacy theming system that was the default in v32 and before, for the benefit of applications that have not yet migrated to the Theming API. These themes are deprecated and will be removed in a future major version. You may want to visit the [new theming docs](https://www.ag-grid.com/angular-data-grid/theming/) or check out the [migration guide](https://www.ag-grid.com/angular-data-grid/theming-migration/).

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](https://github.com/ag-grid/ag-grid-customise-theme/tree/master/src/vanilla) or [Webpack and sass-loader](https://github.com/ag-grid/ag-grid-customise-theme/tree/master/src/vanilla-webpack)
- Angular: see our [Angular CLI](https://github.com/ag-grid/ag-grid-customise-theme/tree/master/src/angular) example
- Vue: see our [Vue CLI](https://github.com/ag-grid/ag-grid-customise-theme/tree/master/src/vue) example

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

```scss
@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:

- `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:

```scss
@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:

```html
<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.

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

This can be either:

1. a [provided theme](https://www.ag-grid.com/angular-data-grid/themes/) (`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:

```scss
@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](https://www.ag-grid.com/angular-data-grid/theming-v32-customisation-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](https://www.ag-grid.com/angular-data-grid/theming-v32-customisation-sass-legacy/).

- 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:

```scss
@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.

```scss
@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:

```scss
@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](https://www.ag-grid.com/angular-data-grid/theming-v32-customisation-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:

```scss
@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](https://www.ag-grid.com/angular-data-grid/theming-v32-customisation/#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:

```scss
@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
));
```

> **Note**
>
> `extend-theme` internally uses the Sass `@extend` rule, which generates new selectors for `.ag-theme-acmecorp` while leaving the original selectors for `.ag-theme-quartz` intact. This slightly increases the output of the compiled CSS, but the difference is likely to be too small to measure in real world conditions (less than 1kb gzipped)