Control the look and feel of the grid
The Theming API is a new JavaScript API for styling the grid. In the future it will become the primary way to style the grid. You can choose from our built-in themes, mix and match elements of different themes, and create themes visually using the Theme Builder.
Before v32.2 themes were applied by importing our CSS files and setting a class on the wrapper element e.g. ag-theme-quartz
. The Theming API is an alternative to this technique, and the two cannot be combined on the same page. For more information see Migrating to Theming API.
Key Concepts: Themes, Parts and Parameters
- Core styles are the CSS styles that every grid uses.
- Parameters are configuration values that affect the appearance of the grid. Some, such as
headerTextColor
, affect a single aspect of grid appearance. Others have a wider effect, such asspacing
which adjusts padding across the whole grid. - Parts contain the CSS styles for a single feature like icons or text inputs. We provide a choice of parts so that you can, for example, select a text input style that matches you application, or disable our provided text input styles so that you can write your own.
- Themes are preset configurations of parts and parameters. We provide built-in themes, and you can create your own.
Built-in Themes
- Quartz - Our default theme, with high contrast and generous padding.
- Balham - A more traditional theme modelled after a spreadsheet application.
- Alpine - The default theme before Quartz. We recommend quartz for new projects; this theme is intended to ease migration to the Theming API for applications already using Alpine.
Importing a Built-in Theme
Themes are imported from @ag-grid-community/theming
and provided to grid instances using the theme
grid option. Users of our all-in-one packages such as ag-grid-community
and import themes from there too.
import { themeQuartz } from '@ag-grid-community/theming';
// in template
<ag-grid-vue
:theme="theme"
// Quartz uses the IBM Plex Sans font; load it from Google's CDN
:loadThemeGoogleFonts="true"
...
></ag-grid-vue>
// in component setup hook
setup() {
return {
theme: themeQuartz,
...
};
}
Setting Theme Parameters
Parameters are configuration values that affect the appearance of the grid. The theme.withParams()
method generates a new theme with different default values for its params.
const myTheme = themeQuartz.withParams({
spacing: 12,
accentColor: 'red',
});
Under the hood, theme parameters are implemented using CSS custom properties (variables), and withParams()
sets default values for these, so you can override them in your application stylesheets (see Customising the grid with CSS). However using the API provides validation, typescript autocompletion, and an extended syntax for defining CSS values.
Finding Theme Parameters
There are many parameters available, and several ways of finding the right one to use:
- Theme Builder - In the "Advanced" section of the Theme Builder you can search for parameters and view documentation
- TypeScript auto-complete - When using an editor with TypeScript language support, you can see all available parameters with inline documentation.
- Dev tools - When inspecting an element in the grid, the styles panel shows the CSS custom properties that are being used. A custom property
var(--ag-column-border)
corresponds to the theme parametercolumnBorder
.
Extended Syntax for CSS Values
Length Values
Parameters that refer to on-screen measurements are length values. These will have suffixes like Width, Height, Padding, Spacing etc. They can accept any valid CSS length value, including pixels (10px
) and variable expressions (var(--myLengthVar)
). In addition, the following syntax is supported:
Syntax | Description |
---|---|
4 | A number without units is assumed to be pixels |
{ ref: 'spacing' } | Use the same value as the spacing parameter |
{ calc: '4 * spacing - 2px' } | A CSS calc expression, mapping parameter names to the appropriate CSS custom property. This expression would map to the CSS string "calc(4 * var(--ag-spacing) - 2px)" . Note that - is a valid character in CSS identifiers, so if you use it for subtraction then spaces are required around it. |
Color Values
All parameters ending "Color" are color values. These can accept any valid CSS color value, including named colors (red
), hex values (#FF0000
) CSS functions (rgb(255, 0, 0)
) and variable expressions (var(--myColorVar)
). In addition, the following syntax is supported:
Syntax | Description |
---|---|
{ 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 |
Border Values
All parameters ending "Border" are border values. These can accept any valid CSS border value, such as 1px solid red
and variable expressions (var(--myBorderVar)
). In addition, the following syntax is supported:
Syntax | Description |
---|---|
{ width: 2, style: 'dashed', color: 'blue' } | An object with 3 optional properties. width can take any length value and defaults to 1. style takes a CSS border-style string and defaults to "solid". color takes any color value and defaults to { ref: 'borderColor' } |
true | The default border: {width: 1, style: 'solid' { ref: 'borderColor' } |
false | A shorthand for 0 |
Shadow Values
All parameters ending "Shadow" are shadow values. These can accept any valid CSS box-shadow value, such as 2px 2px 4px 2px rgba(0, 0, 0, 0.5)
and variable expressions (var(--myShadowVar)
). In addition, the following syntax is supported:
Syntax | Description |
---|---|
{ offsetX: 2, offsetY: 2, radius: 4, spread: 2, color: 'rgba(0, 0, 0, 0.5)' } | An object with 5 optional properties. offsetX , offsetY , radius and spread take any length value and default to 0. color takes any color value and defaults to { ref: 'foregroundColor' } |
Font Family Values
All parameters ending "FontFamily" are font family values. These can accept any valid CSS font-family value, such as Arial, sans-serif
and variable expressions (var(--myFontFamilyVar)
). In addition, the following syntax is supported:
Syntax | Description |
---|---|
{ googleFont: 'IBM Plex Sans' } | A Google font. To prevent potential licensing and privacy implications of accidentally loading Google fonts, you must set the loadThemeGoogleFonts grid option to true. A warning will be logged to the console if this option is unset. |
['Arial', 'sans-serif'] | An array of fonts. Each item can be a string font name or a { googleFont: "..." } object. The browser will attempt to use the first font and fall back to later fonts if the first one fails to load or is not available on the host system. |
Image Values
All parameters ending "Image" are image values. These can accept any valid CSS image value, such as url('https://example.com/my-image.png')
and variable expressions (var(--myImageVar)
). In addition, the following syntax is supported:
Syntax | Description |
---|---|
{ url: 'https://example.com/my-image.png' } | Load an image from a URL, or embed a PNG if converted to a data: URL |
{ svg: '<svg> ... SVG string ... </svg>' } | Use an SVG source code string |
Configuring Theme Parts
Parts are objects that contain the CSS styles for a single feature. A theme can only have one part for a given feature, so for example adding a colorScheme
part will remove any existing colorScheme
part.
The theme.withPart(...)
method generates a new theme with the specified part:
import { themeQuartz, colorSchemeDark, iconSetMaterial } from '@ag-grid-community/theming';
// withPart() returns a new theme and calls can be chained
const myTheme = themeQuartz
.withPart(iconSetMaterial)
.withPart(colorSchemeDark);
This example demonstrates mixing and matching any built-in theme, icon set, and color scheme:
Parts Reference
The following parts are available:
- Color schemes:
colorSchemeLight
- neutral light schemecolorSchemeLightCold
- light scheme with subtle cold tint used by Balham themecolorSchemeLightWarm
- light scheme with subtle warm tintcolorSchemeDark
- neutral dark schemecolorSchemeDarkBlue
- our preferred dark scheme used on this websitecolorSchemeDarkWarm
- dark scheme with subtle warm tint
- Icon sets:
iconSetQuartz
- our default icon seticonSetQuartz({strokeWidth: number})
you can call iconSetQuartz as a function to provide a custom stroke width in pixels (the default is 1.5)iconSetQuartzLight
andiconSetQuartzBold
preset lighter and bolder versions of the Quartz icons.
iconSetAlpine
- the icon set used by the Alpine themeiconSetMaterial
- the Material Design icon set
- Checkbox style:
checkboxStyleDefault
- checkbox style used by our themes. There is only one style provided which is configurable through parameters. It being a part allows you to replace it with your own checkbox styles if desired.
- Input style:
inputStyleBase
- unstyled inputs with many parameters to configure their appearanceinputStyleBordered
- inputs with a border around theminputStyleUnderlined
- inputs with a line underneath them as used in Material Design
- Tab styles:
tabStyleBase
- unstyled tabs with many parameters to configure their appearancetabStyleQuartz
- tabs styled as per the Quartz themetabStyleMaterial
- tabs styled as per the Material themetabStyleAlpine
- tabs styled as per the Alpine themetabStyleRolodex
- tabs designed to imitate paper cards, as used by the Balham theme
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 .
Single applications that want to change the appearance of the grid do not need to create their own parts, they can simply add CSS rules into the application's stylesheets.
The createPart
function creates an empty part.
Parts have the following methods:
import { createPart } from '@ag-grid-community/theming';
// 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);
Advanced use cases
Creating Themes From Scratch
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/theming';
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: