Expand All

  Getting Started

  Reference

  Features

  Row Models

  Themes

  Components

  Examples

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

Polymer Datagrid

Here we explain how to use ag-Grid inside an Polymer application. It is broken down into the following sections:

Feature Roadshow

Column Definitions

Columns are configured in the grid by providing a list of Column Definitions. The attributes you set on the column definitions define how the columns behave e.g. title, width etc.
columnDefinitions = [ {field: 'firstName', width: 100px}, {field: 'lastName', width: 100px}, {field: 'phoneNumber', width: 200px} ];

Column Groups

Columns can be grouped together into Column Groups. Additionally you can configure groups to be expandable to show and hide columns within the group.
columnDefinitions = [ {group: 'User Details', children: [ {field: 'firstName', pinned: 'left'}, {field: 'lastName', width: 100}, {field: 'phoneNumber'} ]}; ];

Column Headers

The display of column headers can be fine-tuned to change Header Height and Text Orientation for example.
// set heights as a grid option gridOptions = { headerHeight: 25, headerHeight: 40 } // display text vertically using CSS .ag-header-cell-label .ag-header-cell-text { transform: rotate(90deg); }

Column Resizing

Resize columns by dragging the edge of the column header, Auto Fill to fill the grid width, or Auto Size columns to fit their content.
// get columns to fit the grid width api.sizeColumnsToFit(); // get columns to fit content columnApi.autoSizeAllColumns();

Column Filter

Column Filters appear in the column menu. The grid comes with filters out of the box: text, number, date and set filters. You can also create your own customer filter.
gridOptions = { // turn on filtering enableFilter: true, ... columnDefs: [ {field: "athlete", filter: "text"}, {field: "age", filter: "number"}, {field: "sport", filter: MyCustomerFilter} ]}

Text Filter

Text Filter allows filtering text strings with {equals, notEqual, contains, notContains, startsWith, endsWith}.
colDef = { field: 'athlete', filter: 'text', filterOptions: {'equals', 'contains'} }

Number Filter

Number Filter allows filtering numbers with {equals, notEquals, lessThanOrEqual, greaterThan, greaterThanOrEqual, inRange}
colDef = { field: 'totalWinnings', filter: 'number' }

Date Filter

Date Filter allows filtering dates with {equals, notEquals, lessThanOrEqual, greaterThan, greaterThanOrEqual, inRange}.
colDef = { field: 'date', filter: 'date' }

ag-Grid EnterpriseSet Filter

Set Filter works like Excel, providing checkboxes to select values from a set.
colDef = { field: 'country', filter: 'set' }

Custom Filter

Create your own Custom Filter to match your own business requirements.
colDef = { field: 'name', filter: MyCustomFilter }

Quick Filter

Quick Filter filters all columns simultaneously with a simple text search, just like how you filter your Gmail.
// you pass the filter text to the grid // via the grid's API api.setQuickFilter(searchText)

External Filter

External Filter allows you to build filters that live outside of the grid. For example, you can include your own widgets outside the grid for your own filter.

Row Sorting

Row Sorting will sort the data. Sort a column by clicking the header. Sort multiple columns by holding down shift.
// enable filtering with grid option gridOptions = { enableSorting: true, ... }

Row Selection

Row Selection to select rows. Choose between click selection or checkbox selection. Selecting groups will select children.
// enable sorting with grid option gridOptions = { // set to 'single' or 'multiple' rowSelection: 'multiple', ... }

ag-Grid EnterpriseRange Selection

Drag the mouse over cells to create a Range Selection. This is handy for highlighting data or for copying to the clipboard.
// enable sorting with grid option gridOptions = { enableRangeSelection: true, ... }

Grid Size

Set the Width and Height of the grid using CSS. If your application changes the size of the grid at run time, the grid will dynamically adjust to the new size.
<!-- set using exact pixel --> <ag-grid style="height: 200px; width: 400px;"/> <!-- or set using percent --> <ag-grid style="height: 100%; width: 100%;"/>

Column Spanning

Column Spanning allows cells to span columns, similar to cell span in Excel
colDef = { field: 'country', colSpan: function(params) { // span 2 cols for Russia, otherwise 1 var country = params.data.country; return country==='Russia' ? 2 : 1; } ... };

Column Pinning

Use Columm Pinning to pin one or more columns to the left or to the right. Pinned columns are always present and not impacted by horizontal scroll.
var columns = [ {field: 'athlete', pinned: 'left'}, {field: 'total', pinned: 'right'}, ... ]

Row Pinning

Use Pinned Rows to pin one or more rows to the top or the bottom. Pinned rows are always present and not impacted by vertical scroll.
// set pinned column using grid property gridOptions = { pinnedTopRowData: [], pinnedBottomRowData: [], ... }

Row Height

Rows can have different Row Height. You can even change the row height dynamically at run time.
gridOptions = { // getRowHeight is a grid callback getRowHeight = function(params) { // 25 px for even rows, 50 px for other rows var rowIndex = params.node.rowIndex; var rowEven = rowIndex % 2 === 0; return rowEven ? 25 : 50; }

Cell Styling

Use CSS rules to define Cell Style based on data content, e.g. put a red background onto cells that have negative values, and green on values greater than 100.
cellClassRules = { // put CSS class 'highlight-negative' onto cells // that have negative values. 'highlight-negative': 'x < 0' 'highlight-large-value': 'x > 100' }

Value Handlers

Each grid column typically has a field where it gets the value to display. However you can provide more logic here to get finer control over how data is retrieved (for display) and stored (after editing) with the family of Value Handlers.

Value Getters & Value Formatters

Value Getters & Value Formatters are about getting and formatting the data to display. Use Value Getters when the data is not a simple field. Use Value Formatters to format values for display.
var columns = [ // two simple cols, A and B {field: 'a'}, {field: 'b'}, // total column, giving sum of A and B {headerName: 'Total', valueGetter: function(params) { var data = params.data; return data.a + data.b; } }, {field: 'price', // simple currency formatter putting in dollar sign valueFormatter: function(params){ return '$' + params.value; }, } ];

Setters and Parsers

Value Setters and Value Parsers are the inverse of value getters and value formatters. Value setters are for placing values into data when field cannot be used. Value parser is for parsing edited values, e.g. removing formatting before storing into the data.
var columns = [ // this example assumes the data is in an array, // so you want to access indexes of the array rather // than using field { // value getter returns first array element valueGetter: function(params) { var data = params.data; return data[0]; }, // value setter sets first array element valueSetter: function(params) { var data = params.data; data[0] = params.newValue; } }, // this column is for a number, the default editor sets // strings, so we convert the string to a number { field: 'amount', valueFormatter: function(params){ return Number(params.newValue); } } ];

Expressions

Expressions allow you to use simple strings instead of functions for value getters, setters, formatters and parsers.
var columns = [ { valueGetter: 'data[0]', valueSetter: 'data[0] = newValue', valueFormatter: '"$"+value', valueParser: 'Number(params.newValue)' } ];

Value Cache

The Value Cache is used to store results of value getters. It is always on, enhancing the performance of the grid.

Reference Data

Use Reference Data for easier editing of data that uses reference data for display. For example, you might have country codes in your data e.g. {IE, UK, USA} but you display values e.g. {Ireland, Great Britain, United States of America}). Using reference data simplifies this, especially if editing.

Cell Rendering

Use Cell Rendering to have cells rendering values other than simple strings. For example, put country flags beside country names, or push buttons for actions.
colDef = { field: 'country', cellRenderer: MyCountryCellRenderer ... }

Cell Editing

Users can update data with Cell Editing. Use one of the provided cell editors or create your own to suit your business needs.
colDef = { field: 'country', cellEditor: 'richSelect', cellEditorParams: { values: ['Ireland','United Kingdom'] } ... }

Keyboard Navigation

With Keyboard Navigation users can use cursor keys and tab keys to navigate between cells.

Touch Support

User can navigate the features of the grid on a touch device with the built-in Touch Support. You don't need to do anything, it works out of the box.

Animation

Rows in the grid will Animate into place after the user sorts or filters.
gridOptions = { animateRows: true ... }

Accessing Data

Once data is in the grid, you can Access the Data using the grid's API.
// get the number of displayed rows gridApi.getDisplayedRowCount() // get the first row gridApi.getDisplayedRowAtIndex(0);

Pagination

Use Pagination when you don't want the user to have to scroll. Pagination allows viewing rows one page at a time.
gridOptions = { pagination: true, ... }

Updating Data

Data can be updated in real time. The grid can highlight the change by flashing the cells or by animation inside the cell as the cell refreshes.
// get a reference to the right row var rowNode = api.getRowNode('22'); // set new value into the row rowNode.setDataValue('bid', 33.24);

View Refresh

If the data changes outside of the grid, get the grid to do a View Refresh to update the UI to the latest values. The grid will use change detection to only refresh values that have changed.
// refresh all cells in the grid gridApi.refreshCells();

Change Detection

As you change data inside the grid, the grid runs Change Detection to check if any other cells need to be updated to reflect the change.

Internationalisation

Support multiple languages with Internationalisation.
gridOptions = { localeText: { lessThanOrEqual: 'menor o igual', greaterThanOrEqual: 'mayor o igual', ... } }

Performance

The core grid engine gives Performance unlike that seen before. The grid uses row and column virtualisation, animation frames and many other techniques.

Accessibility

The grid has ARIA roles inside the cells for Accessibility to enable navigation with screen readers.
<div role="row"> <div role="gridcell"></div> <div role="gridcell"></div> </div>

Full Width Rows

Full Width Rows allow you to have one cell that spans the entire width of the tables. This allows a card layout to work alongside the normal cells.
gridOptions = { isFullWidthCell: function(rowNode) { // return every second row as full width return rowNode.rowIndex % 2 === 0; }, // use custom component for the full width row fullWidthCellRenderer: MyCardComponent }

ag-Grid EnterpriseMaster Detail

Use Master Detail to expand rows and have another grid with different columns inside.

Aligned Grids

Have one or more grids horizontally Aligned so that any column changes in one grid impact the other grid. This allows two grids with different data to be kept horizontally in sync.

CSV Export

Use CSV Export to take data out of the grid and into another application for further processing such as Excel.

ag-Grid EnterpriseExcel Export

Export in native Excel Format which will maintain the column widths and also allow exporting of styles. For example, you can color cells in the grid and have the equivalent cells colored in the Excel export.

RTL

Use Right to Left alignment to allow languages such as Arabic & Hebrew.

Custom Icons

All the icons in the grid can be replaced with your own Custom Icons. You can either use CSS or provide your own images.
gridOptions = { icons: { // use font awesome for menu icons menu: '<i class="fa fa-bath"/>', filter: '<i class="fa fa-long-arrow-down"/>', columns: '<i class="fa fa-handshake-o"/>' } ... }

Overlays

Full control of Overlays to display messages to the user on top of the grid

Layout For Print

Use For Print to have the grid render without using any scrollbars. This is useful for printing the grid, where all rows should be printed, not just what's visible on the screen.

ag-Grid EnterpriseGrouping Rows

Use Grouping Rows to group the data over selected dimensions. You can set the data to group by specific columns, or allow the user to drag and drop columns of their choice and have it grouped on the fly.
columnDefs = [ {field: 'country', rowGroup: true}, {field: 'sport'}, ... ]

ag-Grid EnterpriseTree Data

Use Tree Data to display data that has parent / child relationships where the parent / child relationships are provided as part of the data. For example, a folder can contain zero or more files and other folders.

ag-Grid EnterpriseAggregation

When grouping you can also do Aggregation to get aggregate values for the data i.e. sum, min, max etc. Use the built in aggregate functions or create your own.
columnDefs = [ {field: 'country', rowGroup: true}, {field: 'gold', aggFunc: 'sum'}, ... ]

ag-Grid EnterprisePivoting

Make columns out of values by Pivoting on the data, similar to Pivot Tables in Excel.
columnDefs = [ {field: 'country', rowGroup: true}, {field: 'sport', pivot: true}, {field: 'gold', aggFunc: 'sum'}, ... ]

ag-Grid EnterpriseTool Panel

The Tool Panel allows the user to manipulate the list of columns, such as show and hide, or drag columns to group or pivot.
gridOptions: { showToolPanel: true, ... }

ag-Grid EnterpriseClipboard

Copy and paste data to and from the Clipboard. Users will be able to edit data in Excel, then copy the data back into the grid when done.

ag-Grid EnterpriseColumn Menu

The Column Menu drops down from the column header. Use the default options or provide your own.

ag-Grid EnterpriseContext Menu

The Context Menu appears when you right click on a cell. Use the default options or provide your own.

ag-Grid EnterpriseStatus Bar

The Status Panel appears on the bottom of the grid and shows aggregations (sum, min, max etc.) when you select a range of cells using range selection. This is similar to what happens in Excel.

ag-Grid EnterpriseLicense Key

Each customer of ag-Grid Enterprise will be given a License Key to put into their application.