--- title: "Theming: Colours & Dark Mode" framework: react version: "36.1.0" --- # Theming: Colours & Dark Mode Control the overall colour scheme and colour of individual elements ## Overview - Change individual [colour parameters](#colour-parameters) - Switch between [light and dark colour schemes](#colour-schemes) using parts - Integrate with a website that has a dark mode toggle using [theme modes](#theme-modes) - Make unrestricted [customisations using CSS](https://www.ag-grid.com/react-data-grid/theming-css/#custom-css-rules) ## Colour Parameters The grid has a few key colour parameters that most applications will set custom values for, and many more specific colour 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 colour - `accentColor` - the colour used for highlights and selection; your organisation's primary brand colour often works well. Key colours are mixed together to make default values for all other colours that you can override to fine tune the colour scheme. For example, the default border colour is generated by mixing the background and foreground colours at a ratio of 85% background to 15% foreground. This can be overridden by setting the `borderColor` parameter. Some commonly overridden colour parameters are: - `borderColor` - the colour of all borders, see also [Customising Borders](https://www.ag-grid.com/react-data-grid/theming-borders/) - `dataBackgroundColor` - the background colour of the grid data area - `headerBackgroundColor` - the background colour of the header rows - `chromeBackgroundColor` - the background colour of the grid's chrome (header, tool panel, etc) - `textColor` - the color for all text unless overridden by a more specific parameter - `headerTextColor` - the color of text in the header - `cellTextColor` - the color of text in data cells Many more colour parameters are available. See the [Colours section](https://www.ag-grid.com/react-data-grid/theming-api/#reference-colours) of the parameters reference for the core colour parameters, or search "color" in the "All Parameters" section of the [Theme Builder](https://www.ag-grid.com/theme-builder/) for a full list of colour parameters. For example: ```js 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)', }); ``` #### Colour Customisation ```tsx "use client"; import React, { useCallback, useMemo, useRef, useState, StrictMode, } from "react"; import { createRoot } from "react-dom/client"; import { AgGridReact, AgGridProvider } from "ag-grid-react"; import { AllCommunityModule, ColDef, ColGroupDef, GridApi, GridOptions, ModuleRegistry, Theme, enableDevValidations, themeQuartz, } from "ag-grid-community"; import { IOlympicData } from "./interfaces"; import { useFetchJson } from "./useFetchJson"; if (process.env.NODE_ENV !== "production") { enableDevValidations(); } const modules = [AllCommunityModule]; 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)", }); const GridExample = () => { const containerStyle = useMemo(() => ({ width: "100%", height: "100%" }), []); const gridStyle = useMemo(() => ({ height: "100%", width: "100%" }), []); const [columnDefs, setColumnDefs] = useState([ { field: "athlete", minWidth: 170 }, { field: "age" }, { field: "country" }, { field: "year" }, { field: "date" }, ]); const theme = useMemo(() => { return myTheme; }, []); const defaultColDef = useMemo(() => { return { editable: true, filter: true, }; }, []); const { data, loading } = useFetchJson( "https://www.ag-grid.com/example-assets/olympic-winners.json", ); return (
rowData={data} loading={loading} columnDefs={columnDefs} theme={theme} defaultColDef={defaultColDef} />
); }; const root = createRoot(document.getElementById("root")!); root.render( , ); ``` [Live example: Colour Customisation](https://www.ag-grid.com/examples/theming-colors/color-customisation/reactFunctionalTs) ## Extended Syntax for Colour Values All theme parameters with the suffix `Color` are colour values, and can accept the following values: | Syntax | Description | | --- | --- | | `string` | A [CSS colour value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value), such as `'red'`, `'rgb(255, 0, 0)'`, or variable expression `'var(--myColorVar)'`. | | `{ 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` | ## Colour Schemes The grid defines a number of dark and light colour schemes that you can apply. - `colorSchemeVariable` - the default colour scheme for all our [built-in themes](https://www.ag-grid.com/react-data-grid/themes/#built-in-themes). By default it appears light, but can be adjusted using [theme modes](#theme-modes) (see below). - `colorSchemeLight` - a neutral light colour scheme - `colorSchemeLightWarm`, `colorSchemeLightCold` - light colour schemes with subtle warm and cold tints - `colorSchemeDark` - a neutral dark colour scheme - `colorSchemeDarkWarm` - dark colour scheme with subtle warm tint - `colorSchemeDarkBlue` - blue tinted colour scheme as used in dark mode on this website Colour schemes are applied to themes using `withPart()`: ```js import { colorSchemeDark } from 'ag-grid-community'; const myTheme = themeQuartz.withPart(colorSchemeDark); ``` #### Colour Scheme ```tsx 'use client'; import React, { StrictMode } from "react"; import { createRoot } from "react-dom/client"; import { AllCommunityModule, colorSchemeDarkBlue, colorSchemeDarkWarm, colorSchemeLightCold, colorSchemeLightWarm, themeQuartz, } from "ag-grid-community"; import { AgGridProvider, AgGridReact } from "ag-grid-react"; const themeLightWarm = themeQuartz.withPart(colorSchemeLightWarm); const themeLightCold = themeQuartz.withPart(colorSchemeLightCold); const themeDarkWarm = themeQuartz.withPart(colorSchemeDarkWarm); const themeDarkBlue = themeQuartz.withPart(colorSchemeDarkBlue); const GridExample = () => { return (

colorSchemeLightWarm:

colorSchemeLightCold:

{ }
{ }

colorSchemeDarkWarm:

colorSchemeDarkBlue:

{ }
{ }
); }; const rowData: any[] = (() => { const rowData: any[] = []; for (let i = 0; i < 10; i++) { rowData.push({ make: "Toyota", model: "Celica", price: 35000 + i * 1000 }); rowData.push({ make: "Ford", model: "Mondeo", price: 32000 + i * 1000 }); rowData.push({ make: "Porsche", model: "Boxster", price: 72000 + i * 1000, }); } return rowData; })(); const columnDefs = [{ field: "make" }, { field: "model" }, { field: "price" }]; const defaultColDef = { editable: true, flex: 1, minWidth: 100, filter: true, }; const root = createRoot(document.getElementById("root")!); root.render( , ); ``` [Live example: Colour Scheme](https://www.ag-grid.com/examples/theming-colors/color-scheme/reactFunctionalTs) A colour scheme is simply a theme part with values defined for the key colour parameters, so if none of the built-in schemes suit, choose the one that is closest to your needs and override parameters as required: ```js const myTheme = themeQuartz .withPart(colorSchemeDarkBlue) .withParams({ // We prefer red to blue. Because the built in colour schemes // derive all colours from foreground, background and // accent colours, 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` colour scheme, which is the default for our [built-in themes](https://www.ag-grid.com/react-data-grid/themes/#built-in-themes), the colour scheme can be controlled by setting the `data-ag-theme-mode="mode"` attribute on the `` or `` elements, where `mode` is one of: - `light` - `dark` - `dark-blue` > **Note** > > If your grid is inside Shadow DOM or you only want to change the mode of some grids on the page, you may set the attribute on any ancestor element of the grid that has the `ag-theme-mode` class on it: > > ```html >
> ... >
> ``` You can also define custom colour modes by passing the mode name as the second argument to `withParams`. This example defines custom colour schemes for light and dark mode and switches between them by setting the `data-ag-theme-mode` attribute on the `body` element: ```js const myTheme = themeQuartz .withParams( { backgroundColor: '#FFE8E0', foregroundColor: '#361008CC', browserColorScheme: 'light', }, 'light-red' ) .withParams( { backgroundColor: '#201008', foregroundColor: '#FFFFFFCC', browserColorScheme: 'dark', }, 'dark-red' ); ``` #### Theme Mode ```tsx 'use client'; import React, { StrictMode } from "react"; import { createRoot } from "react-dom/client"; import { themeQuartz } from "ag-grid-community"; import { AllEnterpriseModule } from "ag-grid-enterprise"; import { AgGridProvider, AgGridReact } from "ag-grid-react"; const theme = themeQuartz .withParams( { backgroundColor: "#FFE8E0", foregroundColor: "#361008CC", browserColorScheme: "light", }, "light-red", ) .withParams( { backgroundColor: "#201008", foregroundColor: "#FFFFFFCC", browserColorScheme: "dark", }, "dark-red", ); const GridExample = () => { return (

); }; function setDarkMode(enabled: boolean) { document.body.dataset.agThemeMode = enabled ? "dark-red" : "light-red"; } setDarkMode(false); const rowData: any[] = (() => { const rowData: any[] = []; for (let i = 0; i < 10; i++) { rowData.push({ make: "Toyota", model: "Celica", price: 35000 + i * 1000 }); rowData.push({ make: "Ford", model: "Mondeo", price: 32000 + i * 1000 }); rowData.push({ make: "Porsche", model: "Boxster", price: 72000 + i * 1000, }); } return rowData; })(); const columnDefs = [{ field: "make" }, { field: "model" }, { field: "price" }]; const defaultColDef = { flex: 1, minWidth: 100, filter: true, enableValue: true, enableRowGroup: true, enablePivot: true, }; const root = createRoot(document.getElementById("root")!); root.render( , ); ``` [Live example: Theme Mode](https://www.ag-grid.com/examples/theming-colors/theme-mode/reactFunctionalTs)