Introducing Our New Theming API

In AG Grid 32.2 we released our new Theming API. This API is designed to provide detailed control over the grid’s appearance without touching any CSS, making it easier for developers to customise existing themes or create new ones.

Whilst you can still use CSS to customise the Grid, the Theming API is intended to become the primary method for styling AG Grid in future releases.

Why the Theming API?

Traditionally, AG Grid themes were applied by importing predefined CSS files and assigning a theme class (e.g., ag-theme-quartz) to the grid's wrapper element, like so:

import '@ag-grid-community/styles/ag-grid.css'; // Core CSS
import '@ag-grid-community/styles/ag-theme-quartz.css'; // Theme-specific CSS

return (
 <div
  className="ag-theme-quartz" // applying the theme
  style={{ height: 500 }}
 >
   <AgGridReact
       // GridOptions...
   />
 </div>
)

The Theming API is an alternative approach which allows you to:

• Customise themes using JavaScript: Instead of using unchecked CSS custom properties (variables) to change the appearance of a theme, you can now benefit from TypeScript validation and code completion and use Theming API parameters to style elements directly from your code
• Mix and Match Elements: Combine elements from different themes to create a unique look.
• Use the Theme Builder: The Theme Builder is specifically designed to work with this new API and allows you to visually design themes without delving deep into code.

Key Concepts: Themes, Parts, and Parameters

Before getting started with the new API, it is worth understanding the different aspects that make up the API:

1. Parameters

Parameters are configuration values that influence the grid's appearance. They can range from affecting a single aspect, like headerTextColor, to having a broader impact, such as spacing, which adjusts padding across the grid.

2. Parts

Parts contain the CSS styles for a single feature like icons or text inputs. We provide a choice of parts to allow you to, for example, select a text input style that matches your application, or disable our provided text input styles to write your own.

3. Themes

Themes are preset configurations that define the overall appearance of the grid. They are combinations of various parts and parameters. AG Grid offers several built-in themes:

• Quartz: Modern-looking theme with high contrast and generous padding. This is the recommended grid theme and an excellent choice for most applications.
• Balham: Balham has a more traditional look modelled after a spreadsheet application. It is appropriate for applications that need to fit more data onto each page.
• Alpine: Alpine was the default theme before Quartz was released. It is still supported, but we recommend Quartz for new applications.

Getting Started with the Theming API

Importing a Built-in Theme

Using the Theming API still requires importing your chosen theme, however, instead of importing the CSS file(s), you can instead import the theming module. This can then be assigned to your grid instance via the theme grid option:

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

const gridOptions = {
    theme: themeQuartz,
};

Customising Themes with Theme Parameters

To customise your theme, you can create a new theme by adjusting the existing theme parameters by using the withParams method, and passing through the parameters you want to override:

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

Under the hood, theme parameters utilize CSS custom properties (variables). While you can override these in your stylesheets, using the API provides benefits like validation and TypeScript autocompletion.

Once you've created your custom theme, you can apply it via the theme grid option:

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

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

const gridOptions = {
  theme: myTheme,
  // Other grid options...
};

Finding the Right Parameters

To find the parameters you want to override in any given theme you can use either:

• TypeScript Auto-complete: Leverage inline documentation and suggestions in your code editor.
• Theme Builder: Search and explore parameters in the "Advanced" section, complete with documentation.
• Developer Tools: Inspect grid elements to see the CSS custom properties in use.

Combining Elements from Multiple Themes

One of the key features of the Theming API is its ability to mix and match parts of various themes, for example integrating the Material icon set into the Quartz theme, or using the Quartz colour scheme with the Alpine theme.

To mix and match themes, you can use the withPart API. This works in a similar fashion to the withParams API - all you need to do is import the part you want to include in your theme and pass this to the withParams API:

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

const myTheme = themeQuartz
    .withPart(iconSetMaterial)
    .withPart(colorSchemeDark);

Parts Reference

Our initial release offers a variety of parts to choose from, including:

• Colour Schemes
• Icon Sets
• Checkbox Styles
• Input Styles
• Tab Styles

Creating Your Own Parts

In addition to using parts from AG Grid themes, you can create custom parts to build a library of reusable styles and share them among many applications.

To do this, you can use the createPart API to create an empty part and then use the following methods to configure the part:

• withCSS: Provide specific CSS rules to apply to your grid.
• withAdditionalParams: Provide parameters which can then be called from your CSS rules.
• withParams: Use any of the Theming API parameters.

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

const myCheckboxStyle = createPart('checkboxStyle')
    .withAdditionalParams({
        checkboxGlowColor: { ref: 'foregroundColor', mix: 0.5 },
    })
    .withCSS(`
        .ag-checkbox-input {
            box-shadow: 0 0 5px 4px var(--ag-checkbox-glow-color);
            /* Additional custom styles */
        }
    `)
    .withParams({ accentColor: 'red' });

const customTheme = themeQuartz.withPart(myCheckboxStyle);

Migrating to the Theming API

We've created a comprehensive guide for developers transitioning from the traditional theming method to walk you through Migrating to Theming API.

Remember: the two theming methods cannot coexist on the same page.

Conclusion

We hope this new API will simplify the customisation of the grid, especially for developers. We're still supporting the old way of doing things, but the API will be our recommended approach moving forward, and we'd encourage you to consider migrating. As always, we're keen to hear your feedback which you can share by raising an issue on our AG Grid GitHub repo.

Want to get started? Head over to Theming API documentation to start customising and building themes for your React Table: