JavaScript Data GridTheming: Customising the grid with CSS

Customising the grid with CSS

A running grid instance contains thousands of DOM elements, and each of them has class names like ag-header and ag-row that can be used in CSS rules that change the style of that element.

The Theming API works by generating CSS that is inserted into your document. These styles are just a starting point, and you can use your own CSS to create advanced customisations.

Overriding Theme Parameters with Custom Properties

Themes created by the theming API support over a hundred Theme Parameters. The values provided through the theming API are default values, and can be overridden using CSS, meaning that many grids can share the same theme and CSS can be used to create differences between the grids.

The names of the CSS custom properties are prefixed with --ag- to avoid conflicts with other custom properties in your application, and use kebab-case:

body {
    /* override value of backgroundColor, foregroundColor and spacing parameters */
    --ag-background-color: #880000;
    --ag-foreground-color: #00000088;
    --ag-spacing: 4px;
}

TODO example here (due in AG-13129)

Values for CSS custom properties are inherited by child elements. The above example sets the variable on the body element, so will affect every grid on the page. You can use different selectors to target individual grids or groups of grids.

Using Your App's Existing Custom Properties

If your app already defines a colour scheme using CSS variables and you want to use those existing variable names within the grid, you can connect the grid variables to your own variables using var() expressions:

body {
    /* use --appMainTextColor as the foreground color for all grids on the page */
    --ag-foreground-color: var(--appMainTextColor);
}

Custom CSS Rules

Some design effects can't be achieved through CSS variables alone. For example, there is no variable to set the font-style on header cells. If you want your column headers to be italic, use regular CSS.

.ag-header-cell-label {
    font-style: italic;
}

TODO example here (due in AG-13129)

The best way to find the right class name to use in a CSS rule is using the browser's developer tools. You will notice that components often have multiple class names, some more general than others. For example, the row grouping panel is a component onto which you can drag columns to group them. The internal name for this is the "column drop" component, and there are two kinds - a horizontal one at the top of the header and a vertical one in the columns tool panel. You can use the class name ag-column-drop to target either kind, or ag-column-drop-vertical / ag-column-drop-horizontal to target one only.

Understanding CSS rule maintenance and breaking changes

With each release of the grid we add features and improve existing ones, and as a result the DOM structure changes with every release - even minor releases. Of course we test and update the CSS rules in our themes to make sure they still work, and this includes ensuring that customisations made via CSS variables does not break between releases. But if you have written your own CSS rules, you will need to test and update them.

The simpler your CSS rules are, the less likely they are to break between releases. Prefer selectors that target a single class name where possible.

Avoiding Breaking the Grid with CSS Rules

Browsers use the same mechanism - CSS - for controlling how elements work (e.g. scrolling and whether they respond to mouse events), where elements appear, and how elements look. Our "structural stylesheet" (ag-grid.scss) sets CSS rules that control how the grid works, and the code depends on those rules not being overridden. There is nothing that we can do to prevent themes overriding critical rules, so as a theme author you need to be careful not to break the grid. Here's a guide:

• Visual styles including margins, paddings, sizes, colours, fonts, borders etc are all fine to change in a theme.

• Setting a component to display: flex and changing flex child layout properties like align-items, align-self and flex-direction is probably OK if you're trying to change how something looks on a small scale, e.g. to change the alignment of some text or icons within a container; but if you're trying to change the layout of the grid on a larger scale e.g. turning a vertical scrolling list into a horizontal one, you are likely to break Grid features.

• The style properties position, overflow and pointer-events are intrinsic to how the grid works. Changing these values will change how the grid operates, and may break functionality now or in future minor releases.