Search

JavaScript Data GridTheming API: Colors & Dark Mode

The grid provides several ways to customise colours

Overview

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, and you can override these defaults 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)',
});

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 params, so if none of the built-in schemes suit you can use params to create the same effect, and fine-tune the colours to your requirements. For example, colorSchemeDarkBlue is equivalent to:

const myTheme = themeQuartz.withParams({
    backgroundColor: '#1f2836',
    foregroundColor: '#FFF',
    chromeBackgroundColor: {
        ref: 'foregroundColor',
        mix: 0.07,
        onto: 'backgroundColor',
    },
    browserColorScheme: 'dark',
});

Theme Modes

The theme grid option can be updated after the grid is initialised, so for most applications that need to change color scheme, e.g. to implement a dark mode toggle, you can create a light theme and a dark theme and switch between them as required.

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
  • light-warm
  • light-cold
  • dark
  • dark-warm
  • 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'
    );