Expand All

  Getting Started

  Reference

  Features

  Row Models

  Themes

  Components

  Examples

  Third Party

Misc

Github stars make projects look great. Please help, donate a star, it's free.
Read about ag-Grid's Partnership with webpack.
Get informed on releases and other ag-Grid news only - never spam.
Follow on Twitter

Themes

ag-Grid is designed to have its look and feel derived from a theme.

Out of the box, five themes are provided: ag-fresh, ag-blue, ag-dark, ag-material and ag-bootstrap.

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 ag-fresh theme:
<div ag-grid="gridOptions" class="ag-fresh"></div>

The following is an example of using the ag-dark theme:
<div ag-grid="gridOptions" class="ag-dark"></div>

We are currently upgrading the provided themes. If you are using an old theme, you have the choice to move to a new theme. We will continue to keep the old themes for backwards compatibility. The current status of the themes is as follows:

Old ThemeNew ThemePreference
ag-fresh-Use ag-fresh for now
ag-dark-Use ag-dark for now.
ag-blue-Use ag-blue for now.
ag-materialag-theme-materialStart using ag-theme-material

In other words, the only theme with a new alternative right now is ag-material.

<!-- If using the material theme, your code was like this: --> <ag-grid <b>class="ag-material"</b>></ag-grid> <!-- To use the new theme, change it to this: --> <ag-grid <b>class="ag-theme-material"</b>></ag-grid>

Changing the themes is not an easy task. We have decided to do the material theme first and plan to do the other themes in future releases.

If you are not using the provided themes, this will not impact you. The CSS classes used inside ag-Grid remain the same.

When to Create a Theme

You have the following options when choosing a theme:

  1. Use one of the provided themes eg ag-fresh.
  2. Use one of the provided themes and override particular items to fine tune it.
  3. Create your own theme from scratch. This is the most difficult 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: .ag-pinned-cols-viewport { float: left; position: absolute; overflow: hidden; } 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, see what result you get.

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 diagram 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-cols-container: Contains the pinned rows. This container is within a viewport (ag-pinned-cols-viewport) that scrolls vertically to match the position of the ag-body-viewport. This container does not scroll horizontally.
  • ag-body-container: Contains the non-pinned rows. This container is within a viewport (ag-body-viewport) that scrolls both vertically and horizontally.
Note: Both the ag-header-viewport and ag-pinned-cols-viewport do not have scrollbars. They only scroll in response to changes to the ag-body-viewport.

Core DIV Elements

ag-root
ag-header
ag-pinned-header
ag-header-viewport
ag-header-container
ag-body
ag-pinned-cols-viewport
ag-pinned-cols-container
ag-body-viewport-wrapper
ag-body-viewport
ag-body-container

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.
  • Row & Col Attributes: These attributes can be used to identify rows and columns using CSS selectors.
  • Position Attributes: Nothing to do with style, however they stick out below, so worth mentioning. These are set by ag-Grid to position the rows within the containers. Because rows are virtualised, and widths are dynamic, these attributes cannot be set as classes, they are set as dynamic styles by ag-Grid.
<div class='ag-root ag-layout-normal'> <!-- header --> <div class="ag-header"> <div class="ag-pinned-header"> <!-- pinned header cell --> <div class="ag-header-cell"> <div class="ag-header-label">Athlete</div> </div> <div class="ag-header-cell"> <div class="ag-header-label">Age</div> </div> </div> <div class="ag-header-viewport"> <div class="ag-header-container"> <!-- main header cell --> <div class="ag-header-cell"> <div class="ag-header-label">County</div> </div> <!-- main header cell --> <div class="ag-header-cell"> <div class="ag-header-label">Year</div> </div> <!-- the other header cells... --> </div> </div> </div> <!-- body --> <div class="ag-body"> <div class="ag-pinned-cols-viewport"> <div class="ag-pinned-cols-container"> <div class="ag-row ag-row-even" row="0" style="top: 0px; height: 30px;"> <div class="ag-cell cell-col-0" col="0" style="width: 150px;">Michael Phelps</div> <div class="ag-cell cell-col-1" col="1" style="width: 90px;">23</div> </div> <div class="ag-row ag-row-odd" row="1" style="top: 30px; height: 30px;"> <div class="ag-cell cell-col-0" col="0" style="width: 150px;">Michael Phelps</div> <div class="ag-cell cell-col-1" col="1" style="width: 90px;">19</div> </div> <!-- the other pinned rows... --> </div> </div> <div class="ag-body-viewport-wrapper"> <div class="ag-body-viewport"> <div class="ag-body-container"> <div class="ag-row ag-row-even" row="0" style="top: 0px; height: 30px; width: 830px;"> <div class="ag-cell cell-col-2" col="2" style="width: 120px;">United States</div> <div class="ag-cell cell-col-3" col="3" style="width: 90px;">2008</div> <div class="ag-cell cell-col-4" col="4" style="width: 110px;">24/08/2008</div> <!-- the other row cells... --> </div> <div class="ag-row ag-row-odd" row="1" style="top: 30px; height: 30px; width: 830px;"> <div class="ag-cell cell-col-2" col="2" style="width: 120px;">United States</div> <div class="ag-cell cell-col-3" col="3" style="width: 90px;">2004</div> <div class="ag-cell cell-col-4" col="4" style="width: 110px;">29/08/2004</div> <!-- the other row cells... --> </div> <!-- the other body rows... --> </div> </div> </div> </div> </div>

Styling with For Print

Styling with the option domLayout=forPrint 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.

<div class="ag-root ag-layout-for-print"> <!-- header --> <div class="ag-header-container"> <div class="ag-header-cell" style="width: 120px;"> <span>Athlete</span> </div> <div class="ag-header-cell" style="width: 90px;"> <span>Age</span> </div> <!-- the other headers... --> </div> <div class="ag-body-container"> <div class="ag-row ag-row-even" row="0" style="height: 30px; width: 830px;"> <div class="ag-cell cell-col-0" col="0" style="width: 120px;">Michael Phelps</div> <div class="ag-cell cell-col-1" col="1" style="width: 90px;">United States</div> <!-- the other row cells... --> </div> <div class="ag-row ag-row-odd" row="1" style="height: 30px; width: 830px;"> <div class="ag-cell cell-col-0" col="0" style="width: 120px;">Michael Phelps</div> <div class="ag-cell cell-col-1" col="1" style="width: 90px;">United States</div> <!-- the other row cells... --> </div> <!-- the other rows... --> </div> </div>

Customizing the themes with Sass variables

After September 2017, the ag-Grid themes source files got converted to Sass, using the scss syntax. If you already use Sass in your project, this means that you can change the looks of the theme you use by overriding the theme variables value and referencing the Sass source files afterwards.

// styles.scss // This is an example of the application scss file; // Popular framework project scaffolders like angular-cli support // generating sass enabled projects. // For example, the `ng new` command accepts `--style scss`. // override the font size of the entire grid $ag-root-font-size: 10px; // import the Sass files from the ag-Grid npm package. // // The "~" path prefix below relies on Webpack's sass-loader - // https://github.com/webpack-contrib/sass-loader. @import "~ag-grid/src/styles/ag-grid.scss"; @import "~ag-grid/src/styles/theme-fresh.scss";

A runnable version of the example above is available in the ag-Grid seed Webpack/typescript project.

Following is a list of the most useful Sass variables, their default values for the fresh theme, and a short explanation of their purpose.

Variable Name Value Description
ag-root-font-family "Helvetica Neue",Helvetica,Arial,sans-serif The font family used for the entire grid
ag-root-font-size 14px The default font size for the cells and headers
ag-border-1 1px solid grey The border around the cells
ag-background-1 #f6f6f6 The default background color
ag-foreground-1 #222 The default text color
ag-header-foreground-1 #000 The default header text color
ag-header-background-1 linear-gradient(white, lightgrey) The background of the headers
ag-separator-color #d3d3d3 The color of the separator lines used in the grid UI
ag-cell-focused-border 1px solid darkgrey The border around the focused cell
ag-cell-ltr-no-focus-border-right 1px dotted grey The border between the grid cells (LTR mode)
ag-cell-rtl-no-focus-border-left 1px dotted grey The border between the grid cells (RTL mode)
ag-cell-highlight-border 1px solid darkgreen The border of the highlighted cells
ag-row-selected-background-color powderblue The background of the selected row
ag-row-odd-background-color #f6f6f6 The odd colors of the rows
ag-row-even-background-color white The even colors of the rows
ag-row-floating-background-color #f0f0f0 The floating row background color
ag-row-stub-background-color #f0f0f0 The stub row background color
ag-value-change-delta-up-color darkgreen The color for the increase delta notification
ag-value-change-delta-down-color darkred The color for the decrase delta notification
ag-value-change-value-highlight-background-color #cec The background for the changed cell notification
ag-button-background-1 linear-gradient(white, lightgrey) The background of the buttons
ag-button-foreground-1 #000 The text color of the buttons
ag-button-border-1 #808080 The border of the buttons
ag-select-background white The selection background
ag-select-foreground #222 The selection color

You can examine the full, up-to-date list of the Sass variables and their usage in the source code of the themes. The _theme-common.scss file contains the actual implementation, while the theme-*.scss contain the default variable values for each theme.