Angular Data GridTheming API

Control the look and feel of the grid

The Theming API is a new JavaScript API for styling the grid. In the future it will become the primary way to style the grid. You can choose from our built-in themes, mix and match elements of different themes, and create themes visually using the Theme Builder.

Before v32.2 themes were applied by importing our CSS files and setting a class on the wrapper element e.g. ag-theme-quartz. The Theming API is an alternative to this technique, and the two cannot be combined on the same page. For more information see Migrating to Theming API.

Key Concepts: Themes, Parts and Parameters

Core styles are the CSS styles that every grid uses.
Parameters are configuration values that affect the appearance of the grid. Some, such as headerTextColor, affect a single aspect of grid appearance. Others have a wider effect, such as spacing which adjusts padding across the whole grid.
Parts contain the CSS styles for a single feature like icons or text inputs. We provide a choice of parts so that you can, for example, select a text input style that matches you application, or disable our provided text input styles so that you can write your own.
Themes are preset configurations of parts and parameters. We provide built-in themes, and you can create your own.

Built-in Themes

Quartz - Our default theme, with high contrast and generous padding.
Balham - A more traditional theme modelled after a spreadsheet application.
Alpine - The default theme before Quartz. We recommend quartz for new projects; this theme is intended to ease migration to the Theming API for applications already using Alpine.

Importing a Built-in Theme

Themes are imported from @ag-grid-community/theming and provided to grid instances using the theme grid option. Users of our all-in-one packages such as ag-grid-community and import themes from there too.

import { themeQuartz } from '@ag-grid-community/theming';

// in template
<ag-grid-angular
    [theme]="theme"
    // Quartz uses the IBM Plex Sans font; load it from Google's CDN
    loadThemeGoogleFonts
/>

// in component class
public theme = themeQuartz;

Setting Theme Parameters

Parameters are configuration values that affect the appearance of the grid. The theme.withParams() method generates a new theme with different default values for its params.

const myTheme = themeQuartz.withParams({
    spacing: 12,
    accentColor: 'red',
});

Under the hood, theme parameters are implemented using CSS custom properties (variables), and withParams() sets default values for these, so you can override them in your application stylesheets (see Customising the grid with CSS). However using the API provides validation, typescript autocompletion, and an extended syntax for defining CSS values.

Finding Theme Parameters

There are many parameters available, and several ways of finding the right one to use:

Theme Builder - In the "Advanced" section of the Theme Builder you can search for parameters and view documentation
TypeScript auto-complete - When using an editor with TypeScript language support, you can see all available parameters with inline documentation.
Dev tools - When inspecting an element in the grid, the styles panel shows the CSS custom properties that are being used. A custom property var(--ag-column-border) corresponds to the theme parameter columnBorder.

Extended Syntax for CSS Values

Length Values

Parameters that refer to on-screen measurements are length values. These will have suffixes like Width, Height, Padding, Spacing etc. They can accept any valid CSS length value, including pixels (10px) and variable expressions (var(--myLengthVar)). In addition, the following syntax is supported:

Syntax	Description
`4`	A number without units is assumed to be pixels
`{ ref: 'spacing' }`	Use the same value as the `spacing` parameter
`{ calc: '4 * spacing - 2px' }`	A CSS calc expression, mapping parameter names to the appropriate CSS custom property. This expression would map to the CSS string `"calc(4 * var(--ag-spacing) - 2px)"`. Note that `-` is a valid character in CSS identifiers, so if you use it for subtraction then spaces are required around it.

Color Values

All parameters ending "Color" are color values. These can accept any valid CSS color value, including named colors (red), hex values (#FF0000) CSS functions (rgb(255, 0, 0)) and variable expressions (var(--myColorVar)). In addition, the following syntax is supported:

Syntax	Description
`{ ref: 'accentColor' }`	Use the same value as the `accentColor` parameter
`{ ref: 'accentColor', mix: 0.25 }`	A mix of 25%, `accentColor` 75% transparent
`{ ref: 'accentColor', mix: 0.25, onto: 'backgroundColor' }`	A mix of 25%, `accentColor` 75% `backgroundColor`

Border Values

All parameters ending "Border" are border values. These can accept any valid CSS border value, such as 1px solid red and variable expressions (var(--myBorderVar)). In addition, the following syntax is supported:

Syntax	Description
`{ width: 2, style: 'dashed', color: 'blue' }`	An object with 3 optional properties. `width` can take any length value and defaults to 1. `style` takes a CSS border-style string and defaults to "solid". `color` takes any color value and defaults to `{ ref: 'borderColor' }`
`true`	The default border: `{width: 1, style: 'solid' { ref: 'borderColor' }`
`false`	A shorthand for `0`

Shadow Values

All parameters ending "Shadow" are shadow values. These can accept any valid CSS box-shadow value, such as 2px 2px 4px 2px rgba(0, 0, 0, 0.5) and variable expressions (var(--myShadowVar)). In addition, the following syntax is supported:

Syntax	Description
`{ offsetX: 2, offsetY: 2, radius: 4, spread: 2, color: 'rgba(0, 0, 0, 0.5)' }`	An object with 5 optional properties. `offsetX`, `offsetY`, `radius` and `spread` take any length value and default to 0. `color` takes any color value and defaults to `{ ref: 'foregroundColor' }`

Font Family Values

All parameters ending "FontFamily" are font family values. These can accept any valid CSS font-family value, such as Arial, sans-serif and variable expressions (var(--myFontFamilyVar)). In addition, the following syntax is supported:

Syntax	Description
`{ googleFont: 'IBM Plex Sans' }`	A Google font. To prevent potential licensing and privacy implications of accidentally loading Google fonts, you must set the `loadThemeGoogleFonts` grid option to true. A warning will be logged to the console if this option is unset.
`['Arial', 'sans-serif']`	An array of fonts. Each item can be a string font name or a `{ googleFont: "..." }` object. The browser will attempt to use the first font and fall back to later fonts if the first one fails to load or is not available on the host system.

Image Values

All parameters ending "Image" are image values. These can accept any valid CSS image value, such as url('https://example.com/my-image.png') and variable expressions (var(--myImageVar)). In addition, the following syntax is supported:

Syntax	Description
`{ url: 'https://example.com/my-image.png' }`	Load an image from a URL, or embed a PNG if converted to a data: URL
`{ svg: '<svg> ... SVG string ... </svg>' }`	Use an SVG source code string

Configuring Theme Parts

Parts are objects that contain the CSS styles for a single feature. A theme can only have one part for a given feature, so for example adding a colorScheme part will remove any existing colorScheme part.

The theme.withPart(...) method generates a new theme with the specified part:

import { themeQuartz, colorSchemeDark, iconSetMaterial } from '@ag-grid-community/theming';

// withPart() returns a new theme and calls can be chained
const myTheme = themeQuartz
    .withPart(iconSetMaterial)
    .withPart(colorSchemeDark);

This example demonstrates mixing and matching any built-in theme, icon set, and color scheme:

Parts Reference

The following parts are available:

Color schemes:
- colorSchemeLight - neutral light scheme
- colorSchemeLightCold - light scheme with subtle cold tint used by Balham theme
- colorSchemeLightWarm - light scheme with subtle warm tint
- colorSchemeDark - neutral dark scheme
- colorSchemeDarkBlue - our preferred dark scheme used on this website
- colorSchemeDarkWarm - dark scheme with subtle warm tint
Icon sets:
- iconSetQuartz - our default icon set
  - iconSetQuartz({strokeWidth: number}) you can call iconSetQuartz as a function to provide a custom stroke width in pixels (the default is 1.5)
  - iconSetQuartzLight and iconSetQuartzBold preset lighter and bolder versions of the Quartz icons.
- iconSetAlpine - the icon set used by the Alpine theme
- iconSetMaterial - the Material Design icon set
Checkbox style:
- checkboxStyleDefault - checkbox style used by our themes. There is only one style provided which is configurable through parameters. It being a part allows you to replace it with your own checkbox styles if desired.
Input style:
- inputStyleBase - unstyled inputs with many parameters to configure their appearance
- inputStyleBordered - inputs with a border around them
- inputStyleUnderlined - inputs with a line underneath them as used in Material Design
Tab styles:
- tabStyleBase - unstyled tabs with many parameters to configure their appearance
- tabStyleQuartz - tabs styled as per the Quartz theme
- tabStyleMaterial - tabs styled as per the Material theme
- tabStyleAlpine - tabs styled as per the Alpine theme
- tabStyleRolodex - tabs designed to imitate paper cards, as used by the Balham theme

Creating Your Own Parts

For organisations that create a library of reusable styles and share them among many applications, creating parts can be a convenient way to package up a collection of styles and parameters, allowing applications to choose which .

Single applications that want to change the appearance of the grid do not need to create their own parts, they can simply add CSS rules into the application's stylesheets.

The createPart function creates an empty part.

Parts have the following methods:

import { createPart } from '@ag-grid-community/theming';

// This part is for the checkboxStyle feature - adding it to a theme will
// remove the theme's existing checkboxStyle, if any 
const myCheckboxStyle = createPart('checkboxStyle')
    // Add some CSS to this part. If your application is bundled with Vite you
    // can put this in a separate file and import it with
    // `import checkboxCSS "./checkbox.css?inline"`
    .withCSS(
        `
        .ag-checkbox-input {
            /* Parts' CSS can include new variables - define support
               for them using withAdditionalParams below */
            box-shadow: 0 0 5px 4px var(--ag-checkbox-glow-color);
            ...
        }
        /* styles are scoped to grids using the theme, so won't pollute
           the page's global CSS. This next line will have no effect: */
        body {
            border: solid 50px blue !important;
        }
    `
    )
    // Declare parameters added by the custom CSS and provide default values
    .withAdditionalParams({
        checkboxGlowColor: { ref: 'foregroundColor', mix: 0.5 },
        ...
    })
    // If you want to provide new default values for parameters already defined
    // by the grid, use withParams which provides TypeScript checking
    .withParams({ accentColor: 'red' });

// Use your part in built-in theme
const quartzWithMyCheckboxes = themeQuartz.withPart(myCheckboxStyle);
// Or in a theme you build from scratch
const myCustomTheme = createTheme().withPart(myCheckboxStyle);

Advanced use cases

Creating Themes From Scratch

The createTheme function creates a new theme containing core styles but no parts. If you're going to change most of the parts anyway, starting from a new theme will reduce the bundle size compared to starting with a built-in theme.

import { createTheme, iconSetMaterial } from '@ag-grid-community/theming';

const myCustomTheme = createTheme()
    .withPart(iconSetMaterial)
    .withParams({
        accentColor: 'red',
        foregroundColor: '#660000',
        iconSize: 18,
    });

Note that the checkboxes and text editors in the example below (double click on a cell to edit it) are using the default styles from your web browser, because the parts containing their styles have not been added. This is useful if your application does not contain these features, or if you want a clean base upon which to apply your own checkbox styles.

Multiple Grids

Each grid on the page can have its own theme. In the example below, 3 themes are used by 4 grids. The bottom two grids share a theme (Balham) and use CSS custom properties to achieve different header colours: