A theme designed according to the Google Material Language Specs.
This theme looks great for simple applications with lots of white space, and is the obvious
choice if the rest of your application follows the Google Material Design spec. However the
Material spec doesn't cater for advanced grid features such as grouped columns and tool panels.
If your application uses these features, consider using ag-theme-alpine instead.
To use a theme add the theme class name to the div element that contains your grid. The following is an example of using the balham theme:
<div id="myGrid" class="ag-theme-balham"></div>
You need to ensure that the CSS for your theme is loaded.
Some pre-built bundles, whether downloaded from our website or included in the ag-grid-communityNPM package, already embed the styles. If you are using one of these files you do not need to separately load CSS.
If you're not using a JS bundle with styles embedded, you need to include the theme's styles in the HTML page with a <link> tag. There are a few ways to do this:
You can copy (manually or as part of your app's build) a CSS file from node_modules and serve it with your app.
You can load the theme from a free CDN by adding this code to your page <link rel="stylesheet" href="https://unpkg.com/@firstname.lastname@example.org/dist/styles/ag-theme-balham.css">, making sure that the CSS version matches the JS version you're using. (Note: this is useful for testing but not recommended for production as your app will be unavailable if the unpkg servers are down)
Note that the Material theme requires the Roboto font, and this is not bundled in the material CSS. The easiest way to load Roboto is through Google's CDN:
In order to customise a theme, you need to set up your project to compile Sass files. The recommended way to process your project's Scss
files is through webpack, since it provides various loaders that optimize and reduce the final size of the bundle. We provide a
general webpack example appropriate Vanilla JS and React
projects, and an angular example using Angular CLI.
To customise a theme, include the theme mixin file and then call the mixin passing parameters to customise it. Then add CSS rules for advanced customisation:
// use theme parameters where possible
// or write CSS selectors to make customisations beyond what the parameters support
Important theme parameters
There is a full list of theme parameters below, but a few important ones are:
grid-size is the main control for affecting how tightly data and UI elements are packed together.
All padding and spacing in the grid is defined as a multiple of grid-size,
so increasing it will make most components larger by increasing their internal white
space while leaving the size of text and icons unchanged.
borders controls whether borders are drawn around the grid. There are more border-* variables to provide fine-grained control over which borders are drawn and their color.
row-height height in pixels of a grid row.
header-height height in pixels of a header row.
The provided themes have theme-specific variables to set the color of many elements at once. These are shortcuts for setting several other variables.
alpine-active-color (Alpine only) sets the colour of checked checkboxes, range selections, row selections, selected tab underlines, and input focus outlines
balham-active-color (Balham only) sets the colour of checked checkboxes, range selections, row selections, and input focus outlines
material-primary-color and material-accent-color (Material only) set the colours used for the primary and accent colour roles specified in the Material Design color system. Currently primary color is used for buttons, range selections, selected tab underlines and input focus underlines, and accent color is used for checked checkboxes.
Customising row and header heights
The grid uses DOM virtualisation for rendering large amounts of data,
which means that it needs to know the size of various elements like columns and grid rows in order to calculate their
layout. The grid uses several strategies to work out the right size:
Firstly, the grid will attempt to measure the size of an element. This works when styles have loaded, but will not work if the grid initialises before the theme loads. Our theme customisation examples demonstrate how to wait for CSS to load before initialising the grid (see the cssHasLoaded function).
If CSS has not loaded and one of the provided themes is in use, the grid contains hard-coded fallback values for these themes. For this reason we recommend that if you are extending a provided theme like ag-theme-alpine and have not changed the heights of elements, you do not change the theme name so that the grid knows what fallback sizes to apply.
If neither of the above methods will work for your app (you do not want to delay app initialisation until after CSS has loaded, and are not using a provided theme with heights unchanged) then you should inform the grid about your custom element heights using grid properties. The minimal set of properties you need to set to ensure correct functioning are: rowHeight, headerHeight and minColWidth.
Full list of theme parameters
Here is a list of parameters accepted by the base theme and all themes that extend it, including our provided themes Balham, Alpine and Material. The default values demonstrate the kind of value that is expected (a colour, pixel value, percentage value etc) but if you are using a provided theme then the theme will have changed most of the default values. Note that some values are defined relative to other values using the internal ag-defined helper, so data-color: ag-derived(foreground-color) means that if you don't explicitly set the data-color property it will default to the value of foreground-color.
// Colour of text and icons in primary UI elements like menus
// Colour of text in grid cells
// Colour of text and icons in UI elements that need to be slightly less emphasised to avoid distracting attention from data
// Colour of text and icons in the header
// Color of elements that can't be interacted with because they are in a disabled state
disabled-foreground-color: ag-derived(foreground-color, $opacity: 0.5),
// Background colour of the grid
// Background colour for all headers, including the grid header, panels etc
// Background colour for second level headings within UI components
// Background for areas of the interface that contain UI controls, like tool panels and the chart settings menu
// Background color of selected rows in the grid and in dropdown menus
selected-row-background-color: ag-derived(background-color, $mix: foreground-color 25%),
// Background colour applied to every other row or null to use background-color for all rows
// Background color when hovering over rows in the grid and in dropdown menus, or null for no rollover effect (note - if you want a rollover on one but not the other, set to null and use CSS to achieve the rollover)
// Color to draw around selected cell ranges
// Background colour of selected cell ranges. Choosing a semi-transparent color (opacity of 0.1 to 0.5 works well) will ensure that it looks good when multiple ranges overlap.
range-selection-background-color: ag-derived(range-selection-border-color, $opacity: 0.2),
// Background colour to apply to a cell range when it is copied from or pasted into
// Colour and thickness of the border drawn under selected tabs, including menus and tool panels
// Background colour for cells that provide categories to the current range chart
range-selection-chart-category-background-color: rgba(#00FF84, 0.1),
// Background colour for cells that provide data to the current range chart
range-selection-chart-background-color: rgba(#0058FF, 0.1),
// Rollover colour for header cells
// Colour applied to header cells when the column is being dragged to a new position
// Colour to apply when a cell value changes and enableCellChangeFlash is enabled
value-change-value-highlight-background-color: rgba(#16A085, 0.5),
// Colours to apply when a value increases or decreases in an agAnimateShowChangeCellRenderer cell
// Colour for the "chip" that repersents a column that has been dragged onto a drop zone
// Draw borders around most UI elements
// Draw the few borders that are critical to UX, e.g. between headers and rows.
// Draw decorative borders separating UI elements within components
// Draw borders around sidebar tabs so that the active tab appears connected to the current tool panel
// Colour for border around major UI components like the grid itself, headers, footers and tool panels
border-color: ag-derived(background-color, $mix: foreground-color 25%),
// Colour for borders used to separate elements within a major UI component
// Colour of the border between grid rows, or null to display no border
// Default border for cells. This can be used to specify the border-style and border-color properties e.g. `dashed red` but the border-width is fixed at 1px.
cell-horizontal-border: solid transparent,
// Separator between columns in the header. Displays between all header cells For best UX, use either this or header-column-resize-handle but not both
header-column-separator-color: ag-derived(border-color, $opacity: 0.5),
// Visible marker for resizeable columns. Displays in the same position as the column separator, but only when the column is resizeable. For best UX, use either this or header-column-separator but not both
header-column-resize-handle-color: ag-derived(border-color, $opacity: 0.5),
// Suppress styling of native widgets: . If you want to style these yourself, set this to true. If you only want to disable styling for some kinds of input, you can set this to true and e.g. @include ag-native-inputs((checkbox: false)) which will emit styles for all kinds of input except checkboxes.
toggle-button-width: ag-derived(toggle-button-height, $times: 2),
// CHART SETTINGS
// Color of border around selected chart style
// Color of dot representing selected page of chart styles
// SIZING / PADDING / SPACING
// grid-size is the main control for affecting how tightly data and UI elements are packed together. All padding and spacing in the grid is defined as a multiple of grid-size, so increasing it will make most components larger by increasing their internal white space while leaving the size of text and icons unchanged.
// The size of square icons and icon-buttons
// These 4 variables set the padding around and spacing between widgets in "widget containers" which are parts of the UI that contain many related widgets, like the set filter menu, charts settings tabs etc.
widget-container-horizontal-padding: ag-derived(grid-size, $times: 1.5),
widget-container-vertical-padding: ag-derived(grid-size, $times: 1.5),
widget-horizontal-spacing: ag-derived(grid-size, $times: 1.5),
// Horizontal padding for grid and header cells (vertical padding is not set explicitly, but inferred from row-height / header-height
cell-horizontal-padding: ag-derived(grid-size, $times: 3),
// Horizontal spacing between widgets inside cells (e.g. row group expand buttons and row selection checkboxes)
// Height of grid rows
row-height: ag-derived(grid-size, $times: 6, $plus: 1),
// Height of header rows
// Height of items in lists (example of lists are dropdown select inputs and column menu set filters)
list-item-height: ag-derived(grid-size, $times: 5),
// How much to indent child columns in the column tool panel relative to their parent
column-select-indent-size: ag-derived(grid-size, $plus: icon-size),
// How much to indent child rows in the grid relative to their parent row
row-group-indent-size: ag-derived(cell-widget-spacing, $plus: icon-size),
// How much to indent child columns in the filters tool panel relative to their parent
// Cause tabs to stretch across the full width of the tab panel header
font-family: ("Helvetica Neue", sans-serif),
// The name of the font family you're using
icon-font-family: $ag-theme-base-icon-font-family, // this var exported by ag-theme-base-font-vars.scss
// A URI (data: URI or web URL) to load the icon font from. NOTE: if your icon font is already loaded in the app's HTML page, set this to null to avoid embedding unnecessry font data in the compiled theme.
icons-data: $ag-theme-base-icons-data, // this var exported by ag-theme-base-font-vars.scss
icons-font-codes: $ag-theme-base-icons-font-codes, // this var exported by ag-theme-base-font-vars.scss
// cards are elements that float above the UI
// the default card shadow applies to simple cards like column drag indicators and text editors
// override the shadow for popups - cards that contain complex UI, like menus and charts
popup-shadow: 5px 5px 10px rgba(0, 0, 0, 0.3)