Reference

This section explains how to configure the the grid's properties, events, callbacks and API.

Grid Properties

Most features of the grid are set using grid properties. Eg turn on row animation by setting animateRows = true.

Go to Grid Properties

Grid API

Interacting with the grid at run time is done through the grid API. Eg to get all the selected rows, call api.getSelectedRows().

Go to Grid API

Grid Events

Your application can listen for certain events within the grid to act on them. Eg sortChanged gets fired when the grid is sorted, rowSelected gets fired when a row is selected.

Go to Grid Events

Grid Callbacks

If the grid requires information from your application it is done through a grid callback. Eg getMainMenuItems() is called each time a menu is shown and allows your application to customise the menu.

Go to Grid Callbacks

Column Properties

Columns are configured through column definitions. A column definition contains the column properties. Eg colDef.pinned='left' will set a column to be pinned to the left.

Go to Column Properties

Column API

The column API is similar to the grid API, the difference is that the column API groups a set of API methods relevant to columns. Eg the method columnApi.setColumnVisible('country',false) will cause the 'country' column to be hidden.

Go to Column API

Grid Options

The gridOptions is a 'one stop shop' for the entire interface into the grid. The grid options can be used regardless of the framework you are using, however if you are using a framework, you can additionally achieve what grid options provides with your frameworks bindings. How to configure for the particular framework is explained further down this page.

The example below shows the different type of items on the gridOptions.

var gridOptions = { // PROPERTIES - object properties, myRowData and myColDefs are created somewhere in your application rowData: myRowData, columnDefs: myColDefs, // PROPERTIES - simple boolean / string / number properties pagination: true, rowSelection: 'single', // EVENTS - add event callback handlers onRowClicked: function(event) { console.log('a row was clicked'); }, onColumnResized: function(event) { console.log('a column was resized'); }, onGridReady: function(event) { console.log('the grid is now ready'); }, // CALLBACKS isScrollLag: function() { return false; } }

Once the grid is initialised, then the gridOptions will also have available the grid's api and columnApi as follows:

// get the grid to refresh gridOptions.api.refreshView(); // get the grid to space out its columns gridOptions.columnApi.sizeColumnsToFit();

Listening To Events

In addition to adding event listeners directly onto the gridOptions object, it is possible to register for events, similar to registering for events on native DOM elements. This means there are two ways to listen for events, which again aligns with how DOM elements work. The first is to put an onXXX() method (where XXX = the event name) like in the example above, the second is to register for the event like in the following example:

// create handler function function myRowClickedHandler(event) { console.log('the row was clicked'); } // add the handler function gridOptions.api.addEventListener('rowClicked', myRowClickedHandler);

Events are Asynchronous

Grid events are asynchronous so that the state of the grid will be settled by the time your event callback gets invoked.

Default Boolean Properties

Where the property is a boolean (true or false), then false (or leave blank) is the default value. For this reason, on / off items are presented in such was as the most common usage (which will be the default) is false, eg suppressCellSelection is worded as such as most people will want cell selection to be turned on.

Vanilla JavaScript

If you are using plain Javascript then all of your interaction with ag-Grid will be through the gridOptions.

React

The gridOptions are fully available as stated above for React. However you can take advantage of React's properties and events provided by ag-Grid's React Component. This is done as follows:

  • Properties: Properties are defined by passing React props down to ag-Grid.
  • Callbacks: Callbacks are also placed as React Props.
  • Event Handlers: Event handlers are again placed as React Props.
  • API: The grid API and column API are provided to you via the onGridReady() event callback.

So in summary, in React, everything is done via React Props. Here is an example:

<ag-grid-react-component // useful for accessing the component directly via ref ref="agGrid" // these are simple attributes, not bound to any state or prop rowSelection="multiple" // these are bound props, so can use anything in React state or props columnDefs={this.props.columnDefs} showToolPanel={this.state.showToolPanel} // this is a callback isScrollLag={this.myIsScrollLagFunction.bind(this)} // these are registering event callbacks onCellClicked={this.onCellClicked.bind(this)}" onColumnResized={this.onColumnEvent.bind(this)}" onGridReady={this.onGridReady.bind(this)}" // inside onGridReady, you receive the grid APIs if you want them />

The APIs are accessible through the component itself. This is useful in two situations. The first is by using an ref. In the example above, the ref is given as 'myGrid' which then allows something like this:

<button onClick={() => {this.refs.agGrid.api.deselectAll()}}>Clear Selection</button>

Angular

The gridOptions are fully available as stated above for Angular. However you can take advantage of Angulars properties and events provided by ag-Grids Angular Component. This is done as follows:

  • Attributes: Attributes are defined as normal HTML attributes and set non-bound values.
  • Properties: Properties are defined as HTML attributes enclosed in square brackets and are Angular bound values.
  • Callbacks: Callbacks are actually a type of property, but by convention they are always functions and are not for relaying event information. They are bound as properties using square brackets. As callbacks are not events, they do not impact the Angular event cycle, and as such should not change the state of anything.
  • Event Handlers: Event handlers are defined as HTML attributes enclosed in normal brackets and are Angular bound functions.
  • API: The grid API and column API are accessible through the component.

All of the above (attributes, properties, callbacks and event handlers) are registered using their 'dash' syntax and not camelcase. For example, the property rowAnimation is bound using row-animation. The following example shows some bindings:

<ag-grid-angular // assign an angular ID to the grid #myGrid // these are boolean values, which if included without a value, default to true // (which is different to leaving them out, in which case the default is false) row-animation pagination // these are attributes, not bound, give explicit values here row-selection="multiple" // these are bound properties, bound to the AngularJS 1.x current context (that's what a // scope is called in Angular JS 2) [column-defs]="columnDefs" [show-tool-panel]="showToolPanel" // this is a callback [is-scroll-lag]="myIsScrollLagFunction" // these are registering event callbacks (cell-clicked)="onCellClicked($event)" (column-resized)="onColumnEvent($event)"> </ag-grid-angular>

The APIs are accessible through the component. This is useful in two situations. The first is by using an Angular ID. In the example above, the ID is given as '#myGrid' which then allows something like this:

<button (click)="myGrid.api.deselectAll()">Clear Selection</button>

Polymer

The gridOptions are fully available, you can however you can take advantage of Polymer's properties and events provided by ag-Grid's polymer component. This is done as follows:

Properties

Properties on ag-grid-polymer can be provided in the following three ways:

  • LowerCase: ie: rowanimation
  • CamelCase: ie: rowAnimation
  • Hyphenated Lowercase: ie: row-animation

You can specify the properties in the following ways:

  • On the ag-grid-polymercomponent at declaration time
  • On the gridOptions property

Properties on ag-grid-polymer

<ag-grid-polymer rowData="{{rowData}}" rowAnimation pivot-mode ></ag-grid-polymer>

Here we've specified 3 properties: rowData is provided with two-way binding. rowAnimation and pivot-mode illustrate how you can specify properties in different cases.

Events

All data out of the grid comes through events. You can specify the events you want to listen to in the following ways:

  • On the ag-grid-polymercomponent at declaration time
  • On the gridOptions property
  • On the ag-grid-polymercomponent post creation time, via event listeners
  • On the ag-grid-polymercomponent post creation time, via direct property access

Events on ag-grid-polymer

<ag-grid-polymer onGridReady="{{onGridReady}}"></ag-grid-polymer>

Here we're listening to the gridReady event - as with most events we need to add the "on" prefix.

When defining event listeners in this way it's important to note that the this context will be ag-grid-polymer, not the containing application element. You will have access to the grid's properties directly, but not the application element itself. The api and columnApi are available directly via this.api and this.columnApi.

Events via the gridOptions property

<ag-grid-polymer gridOptions="{{gridOptions}}" > </ag-grid-polymer> this.gridOptions.onColumnResized = (event) => { console.log('event via option 3: ' + event); };

Events via Event Listeners on an instance of ag-grid-polymer

<ag-grid-polymer id="myGrid"> </ag-grid-polymer> this.$.myGrid.addEventListener('columnresized', (event) => { console.log('event via option 1: ' + event.agGridDetails); })

In this case we need to specify an id on the ag-grid-polymer component in order to access it.

The grid's payload will be available on the events agGridDetails property.

Events via direct property access on an instance of ag-grid-polymer

<ag-grid-polymer id="myGrid" > </ag-grid-polymer> this.$.myGrid.oncolumnresized = (event) => { console.log('event via option 2: ' + event.agGridDetails); }

In this case we need to specify an id on the ag-grid-polymer component in order to access it.

The grid's payload will be available on the events agGridDetails property.

Grid Api

The Grid API (both api and columnApi) will only be available after the gridReady event has been fired.

You can access the APIs in the following ways:

  • Store them in the gridReady event - they'll be available via the params argument passed into the event
  • Provide a gridOptions object to the grid pre-creation time. Post creation the APIs will be available on the gridOptions object.

Cell Editors, Cell Renderers, Filters etc

Please see the relevant sections on cell renderers, cell editors and filters for configuring and using Polymer Components in ag-Grid.

VueJS

The gridOptions are fully available as stated above for VueJS. However you can take advantage of VueJS's properties and events provided by ag-Grids VueJS Component. This is done as follows:

  • Attributes: Attributes are defined as normal HTML attributes and set non-bound values.
  • Properties: Properties are defined as HTML attributes prefixed with a colon : and are VueJS bound values.
  • Callbacks: Callbacks are actually a type of property, but by convention they are always functions and are not for relaying event information. They are bound as properties prefixed with a colon :. As callbacks are not events, they do not impact the VueJS event cycle, and as such should not change the state of anything.
  • Event Handlers: Event handlers are defined as HTML attributes prefixed with a colon : and are VueJS bound functions.
  • API: The grid API and column API are accessible through the component.

All of the above (attributes, properties, callbacks and event handlers) are registered using their 'dash' syntax and not camelcase. For example, the property pivotMode is bound using pivot-mode. The following example shows some bindings:

<ag-grid-vue // these are attributes, not bound, give explicit values here rowSelection="multiple" // these are boolean values // (leaving them out will default them to false) :rowAnimation="true" :pivot-mode="true" // these are bound properties :gridOptions="gridOptions" :columnDefs="columnDefs" // this is a callback :isScrollLag="myIsScrollLagFunction" // these are registering event callbacks :modelUpdated="onModelUpdated" :cellClicked="onCellClicked" </ag-grid-vue>

The APIs are accessible through the component. This is useful in two situations. The first is by using an ID. In the example above, the ID is given as '#myGrid' which then allows something like this:

<button @click="<b>myGrid</b>.api.deselectAll()">Clear Selection</button>

Web Components

The gridOptions are fully available as stated above for Web Components. However you can take advantage of Web Components attributes for setting properties and also directly accessing the Web Components DOM object for interacting with the component. This is done as follows:

  • Attributes: Attributes are defined as normal HTML attributes and set non-bound values.
  • Properties: Properties are set directly onto the DOM object using javascript.
  • Callbacks: Callbacks, like properties, are also set directly on the DOM object using javascript.
  • Event Handlers: Event handlers are registered as normal DOM event handlers, using either addEventListener(eventName, handler) or assigning an onXXX method on the DOM object.
  • API: The grid API and column API are accessible through the DOM object.

Bindings are registered using their 'dash' syntax and not camelcase. For example, the property rowAnimation is bound using row-animation.

Properties and callbacks are set using standard camelcase, no changes are done.

Web Components Events are all done using lowercase. This keeps the event handling consistent with native DOM elements, however breaks away from the camel case of how events are managed by the other frameworks ag-Grid supports.

This example shows setting up as a Web Component in HTML. Notice it's simliar to Angular, however no binding of properties or event handling.

<ag-grid-angular // normal id for CSS selector inside Javascript id="myGrid" // these are boolean values, which if included without a value, default to Yes row-animation // these are attributes, not bound, give explicit values here row-height="22" row-selection="multiple" </ag-grid-angular>

Then the callbacks and event handling are done in the Javascript as follows:

var myGrid = document.querySelector('#myGrid'); // calling a method directly on the ag-Grid DOM element. // calling setGridOptions starts up the grid and is mandatory (even if gridOptions is empty) myGrid.setGridOptions(gridOptions); // add events to grid option 1 - add an event listener myGrid.addEventListener('columnresized', function(event) { console.log('got an event via option 1'); }); // add events to grid option 2 - callback on the element myGrid.oncolumnresized = function(event) { console.log('got an event via option 2'); }; // add events to grid option 3 - callback on the grid options // remember we can still use everything in gridOptions, the // Web Components features are all in addition gridOptions.onColumnResized = function(event) { console.log('got an event via option 3'); }; // call something on the API myGrid.api.refreshView(); myGrid.columnApi.sizeColumnsToFit(); // change a property myGrid.quickFilterText = 'sandy'; myGrid.showToolPanel = true;

Aurelia

The gridOptions are fully available as stated above for Aurelia. However you can take advantage of Aurelia's properties and events provided by ag-Grids Aurelia Component. This is done as follows:

  • Events: All data out of the grid comes through events. These use Aurelia event bindings eg model-updated.call="onModelUpdated()". As you interact with the grid, the different events are fixed and output text to the console (open the dev tools to see the console).
  • Properties: All the data is provided to the grid as Aurelia bindings. These are bound onto the ag-Grid properties bypassing the elements attributes. The values for the bindings come from the parent controller.
  • Attributes: When the property is just a simple string value, then no binding is necessary, just the value is placed as an attribute eg row-height.bind="22".
  • Changing Properties: When a property changes value, Aurelia automatically passes the new value onto the grid. This is used in the following locations:
    a) The 'quickFilter' on the top right updates the quick filter of the grid. b) The 'Show Tool Panel' checkbox has its value bound to the 'showToolPanel' property of the grid. c) The 'Refresh Data' generates new data for the grid and updates the rowData property.

The example has ag-Grid configured through the template in the following ways:

// notice the grid has an id called agGrid, which can be used to call the API <ag-grid-aurelia class="ag-theme-balham" // items bound to properties on the controller grid-options.bind="gridOptions" column-defs.bind="columnDefs" show-tool-panel.bind="showToolPanel" row-data.bind="rowData" // boolean values 'turned on' enable-col-resize enable-sorting enable-filter group-headers suppress-row-click-selection tool-panel-suppress-groups tool-panel-suppress-values debug // simple values row-height.bind="22" row-selection="multiple" // event callbacks model-updated.call="onModelUpdated()" cell-clicked.call="onCellClicked($event)" cell-double-clicked.call="onCellDoubleClicked($event)" cell-context-menu.call="onCellContextMenu($event)" cell-value-changed.call="onCellValueChanged($event)" cell-focused.call="onCellFocused($event)" row-selected.call="onRowSelected($event)" selection-changed.call="onSelectionChanged()" before-filter-changed.call="onBeforeFilterChanged()" after-filter-changed.call="onAfterFilterChanged()" filter-modified.call="onFilterModified()" before-sort-changed.call="onBeforeSortChanged()" after-sort-changed.call="onAfterSortChanged()" virtual-row-removed.call="onVirtualRowRemoved($event)" row-clicked.call="onRowClicked($event)" ready.call="onReady($event)" column-everything-changed.call="onColumnEvent($event)" column-row-group-changed.call="onColumnEvent($event)" column-value-changed.call="onColumnEvent($event)" column-moved.call="onColumnEvent($event)" column-visible.call="onColumnEvent($event)" column-group-opened.call="onColumnEvent($event)" column-resized.call="onColumnEvent($event)" column-pinned-count-changed.call="onColumnEvent($event)"> </ag-grid-aurelia>

Next Steps

And that's it Doc, now you know how to interface with the grid. Go now and find out about all the great attributes, properties, callbacks and events you can use.