Themes

The grid is styled using CSS. A set of CSS rules styling the grid is referred to as a theme. The grid comes bundled with provided themes or you can create you own theme by applying CSS styles to the grid.

You have the following options when choosing a theme:

  1. Use one of the provided themes. This is the simplest approach.
  2. Customise one of the provided themes using theme parameters and CSS rules. This requires configuring your project to build Sass files, and allows you to change elements of the look and feel like colours, padding, and borders.
  3. Create your own theme from scratch by extending the base theme. This is the best option for apps that look very different to the provided themes.

When to extend the base theme

If you extend a provided theme and then very extensively alter it to make a totally different design, you may encounter a couple of issues. Firstly, if the provided theme contains design elements that you don't want, you will need to add CSS rules to remove them. Secondly, between releases we may change implementation details of the provided theme in a way that breaks these rules you have added. For these apps that want a look and feel totally different from our provided themes, it is appropriate to extend the base theme. The base theme contains basic configurable borders and sensible default padding but otherwise has no opinionated design elements.

If you extend the base theme but want the icons from a provided theme, this can be done by adding the font from the theme you like. You can find these in the dist/styles/webfont folder of the distribution. Link this font into your application and follow the instructions for configuring a custom icon font.

Understanding theme 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 and patch releases. Of course, we test and update the CSS rules in our themes to make sure they still work. But if you have written your own CSS rules, you will need to test and update them.

This is why it is more stable to use theme parameters than CSS rules to change the look and feel of the grid - if you use theme parameters, the theme takes care of generating CSS from them, so you don't have to update anything between releases.

Sometimes you will have to write CSS however. In this case, bear in mind that 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.

When not to use themes

Themes are intended to change the overall look and feel of a grid. If you want to style a particular column, or a particular header, consider using either cell and header renderers, or applying CSS classes or styles at the column definition level. Sometimes it is possible to achieve the same effect using custom renderers as it is with themes. If so, use whichever one makes more sense for you.

Avoiding breaking the grid with custom themes

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 align 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.