JavaScript Data GridTheming: Colors & Dark Mode

Control the overall color scheme and color of individual elements

Overview

• Change individual colour parameters
• Switch between light and dark color schemes using parts
• Integrate with a website that has a dark mode toggle using theme modes
• Make unrestricted customisations using CSS

Color Parameters

The grid has a few key color parameters that most applications will set custom values for, and many more specific color parameters that can be used for fine tuning. Appropriate default values for many parameters are automatically generated based on the key parameters:

• backgroundColor - typically your application page background (must be opaque)
• foregroundColor - typically your application text color
• accentColor - the color used for highlights and selection; your organisation's primary brand color often works well.

Key colors are mixed together to make default values for all other colors that you can override to fine tune the color scheme. For example, the default border color is generated by mixing the background and foreground colors at a ratio of 85% background to 15% foreground. This can be overridden by setting the borderColor parameter.

Some commonly overridden color parameters are:

• borderColor - the color of all borders, see also Customising Borders
• chromeBackgroundColor - the background color of the grid's chrome (header, tool panel, etc).
• textColor, headerTextColor, cellTextColor - override text colors for UI, for headers and cells respectively

Many more parameters are available, search the "All Parameters" section of the theme builder for a full list.

For example:

const myTheme = themeQuartz.withParams({
    backgroundColor: 'rgb(249, 245, 227)',
    foregroundColor: 'rgb(126, 46, 132)',
    headerTextColor: 'rgb(204, 245, 172)',
    headerBackgroundColor: 'rgb(209, 64, 129)',
    oddRowBackgroundColor: 'rgb(0, 0, 0, 0.03)',
    headerColumnResizeHandleColor: 'rgb(126, 46, 132)',
});

Extended Syntax for Color Values

All theme parameters with the suffix Color are color values, and can accept the following values:

Color Schemes

The grid defines a number of dark and light color schemes that you can apply.

• colorSchemeVariable - the default color scheme for all our built-in themes. By default it appears light, but can be adjusted using theme modes (see below).
• colorSchemeLight - a neutral light color scheme
• colorSchemeLightWarm, colorSchemeLightCold - light color schemes with subtle warm and cold tints
• colorSchemeDark - a neutral dark color scheme
• colorSchemeDarkWarm - dark color scheme with subtle warm tint
• colorSchemeDarkBlue - blue tinted color scheme as used in dark mode on this website

Color schemes are applied to themes using withPart():

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

const myTheme = themeQuartz.withPart(colorSchemeDark);

A color scheme is simply a theme part with values defined for the key color parameters, so if none of the built-in schemes suit, choose the one that is closest to your needs and override parameters as required:

const myTheme = themeQuartz
    .withPart(colorSchemeDarkBlue)
    .withParams({
        // We prefer red to blue. Because the built in color schemes
        // derive all colors from foreground, background and
        // accent colors, changing these two values is sufficient.
        backgroundColor: 'darkred',
        accentColor: 'red',
    });

Theme Modes

The standard way of changing a grid's appearance after initialisation is to update the value of the theme grid option. You might implement a dark mode toggle by preparing light and dark versions of a theme and switching between them in response to a button press.

Often however, a grid application is embedded within a website, and the website and grid application have different codebases. It may not be easy to update the theme grid option in response to the website's dark mode changing.

For this use case we provide theme modes. When a theme uses the colorSchemeVariable color scheme, which is the default for our built-in themes, the color scheme can be controlled by setting the data-ag-theme-mode="mode" attribute on any parent element of the grid, commonly the html or body elements, where mode is any of:

• light
• dark
• dark-blue

It is also possible to define your own color modes, by passing the mode name to the second parameter of withParams. This example defined custom color schemes for light and dark mode and switches between them by setting the data-ag-theme-mode attribute on the body element:

const myTheme = themeQuartz
    .withParams(
        {
            backgroundColor: '#FFE8E0',
            foregroundColor: '#361008CC',
            browserColorScheme: 'light',
        },
        'light-red'
    )
    .withParams(
        {
            backgroundColor: '#201008',
            foregroundColor: '#FFFFFFCC',
            browserColorScheme: 'dark',
        },
        'dark-red'
    );