JavaScript Data GridTheming API: Distributing Shared Themes & Parts

For organisations with multiple applications, you can create your own themes and parts to share styles between applications.

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 .

The createPart function creates an empty part.

Parts have the following methods:

import { createPart } from 'ag-grid-community';

// 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);

Creating Themes From Scratch

Most applications create themes by starting with a built-in theme like themeQuartz and using the withParams and withPart method to generate a new theme.

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';

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: