Themes

ag-Grid is designed to have its look and feel derived from a theme. The following themes are available out of the box:

ag-theme-balham

The default flat light theme which is used in most of the examples in the documentation.

ag-theme-balham-dark

A dark variation of the balham theme, used in the enterprise examples in the documentation.

ag-theme-material

A theme designed according to the Google Material Language Specs.

ag-theme-fresh

A light gray theme.

ag-theme-dark

A dark grey theme.

ag-theme-blue

A light theme with blue headers.

ag-theme-bootstrap

Neutral / white theme that fits well in the context of bootstrap components. Notice: the theme does not have a bootstrap dependency.

To use a theme, add the theme class name to the div element where the ag-Grid directive is attached.

The following is an example of using the balham theme:

The following is an example of using the dark balham theme:

When to Create a Theme

You have the following options when choosing a theme:

1. Use one of the provided themes e.g. ag-theme-balham.
2. Use one of the provided themes and tweak using the provided Sass variables.
3. Create your own theme from scratch. This is the most complex approach and you are more exposed to breaking changes in ag-Grid releases.

You should only create your own theme when options 1 and 2 above don't suit, as it is the most difficult. If you do decide to create your own theme, then you can use one of the provided themes and use that as a template. They can be found on GitHub here: https://github.com/ceolter/ag-grid/tree/master/src/styles.

This section does not provide an example of building a theme as a number of themes are already provided with ag-Grid - these can be used as a basis for any additional themes you may wish to create.

When to Style via 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, there isn't a hard and fast rule.

What to Style via Themes

Any of the CSS classes described below can have style associated with them. However you should be cautious about overriding style that is associated outside of the theme. For example, the ag-pinned-cols-viewport, has the following style:

The style attributes float, position and overflow are intrinsic to how the grid works. Changing these values will change how the grid operates. If unsure, take a look at the styles associated with an element using your browsers developer tools. If still unsure, try it out, if the style you want to apply breaks the grid, then it's not a good style to apply!

Structure Example

The exact structure of the DOM within ag-Grid is dependent on its configuration and what data is present. This page takes the below basic example grid, with one pinned column, as an example to demonstrate the DOM structure. The reader is encouraged to inspect the DOM (using your browsers developer tools) to dig deeper.

High Level Overview

The code below shows the hierarchy of the core div elements which form the four quadrants of the table. The four quadrants are as follows:

• ag-pinned-header: Contains the pinned header cells. This container does not scroll.
• ag-header-container: Contains the non-pinned header cells. This container is within a viewport (ag-header-viewport) that scrolls horizontally to match the position of the ag-body-viewport. This container does not scroll vertically.
• ag-pinned-left-cols-container or ag-pinned-right-cols-container: Contains the pinned rows. This container is within a viewport (ag-body-viewport) that scrolls vertically. This container does not scroll horizontally.
• ag-center-cols-container: Contains the non-pinned rows. This container is within a viewport (ag-center-cols-viewport) that scrolls horizontally.

Detailed Breakdown

Below gives a detailed breakdown of the DOM for the example. In the example, the following is highlighted:

• Classes: These CSS classes can have style associated with them in a theme.

Styling with For Print

Styling with the option domLayout='print' is similar to styling as normal, however the dom layout is much simpler. When laying out for printing, there are no pinned columns and no viewports for scrolling.

Highlighting Rows and Columns

The class ag-row-hover and ag-column-hover are added to cells as the mouse is dragged over the cells row or column.

The example below demonstrates the following:

• CSS class ag-row-hover has background color added to it, so when you hover over a cell, the row will be highlighted.
• CSS class ag-column-hover has background color added to it, so when you hover over a cell or a header, the column will be highlighted.
• If you hover over a header group, all columns in the group will be highlighted.

Customizing the themes with Sass variables

ag-Grid themes are build using Sass. This means that you can change the looks of the theme you use using Sass, by overriding the theme variables value and referencing the Sass source files afterwards.

Some of the things you can change in the theme include:

• Changing the text / header / tool panel foreground and background colors
• Changing the icons size and color
• Changing the cell / row spacing*

For a live example, see: Theme Customization Example Repository:

Following is a list of Sass variables, their default values, and a short explanation of their purpose.

You can examine the full, up-to-date list of the Sass variables and their usage in the source code of the themes.