ag-Grid Angular Overview

Full working examples of ag-Grid and Angular can be found in Github, illustrating (amongst others) rich grids, filtering with angular components, master/detail grid and so on.

Every feature of ag-Grid is available when using the ag-Grid Angular component. The Angular component wraps the functionality of ag-Grid, it doesn't duplicate, so there will be no difference between core ag-Grid and Angular ag-Grid when it comes to features.

Configuring ag-Grid in Angular

You can configure the grid in the following ways through Angular:

  • Events: All data out of the grid comes through events. These use Angular event bindings eg (modelUpdated)="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 Angular 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 rowHeight="22". Notice that boolean attributes are defaulted to true IF they attribute is provided WITHOUT any value. If the attribute is not provided, it is taken as false.
  • Grid API via IDs: The grid in the example is created with an id by marking it with #agGrid. This in turn turns into a variable which can be used to access the grid's controller. The buttons Grid API and Column API buttons use this variable to access the grids API (the APIs are attributes on the controller).
  • Changing Properties: When a property changes value, Angular automatically passes the new value onto the grid. This is used in the following locations in the feature rich grid example above:
    a) The quick filter 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.

Notice that the grid has its properties marked as immutable. Hence for object properties, the object reference must change for the grid to take impact. For example, rowData must be a new list of data for the grid to be informed to redraw.

Sometimes the gridReady grid event can fire before the Angular component is ready to receive it, so in an Angular environment its safer to rely on AfterViewInit instead before using the API.

Providing Angular Components to ag-Grid

In order for ag-Grid to be able to use your Angular components, you need to provide them in the top level module:

@NgModule({ imports: [ BrowserModule, FormsModule, RouterModule.forRoot(appRoutes), AgGridModule.withComponents( [ SquareComponent, CubeComponent, // ...other components

You can then use these components as editors, renderers or filters. For example, to use an Angular Component as a Cell Renderer, you would do the following:

let colDefs = [ { headerName: "Square Component", field: "value", cellRendererFramework: SquareComponent, editable:true, colId: "square", width: 175 }, ...other column definitions ]

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

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-angular #agGrid style="width: 100%; height: 350px;" class="ag-theme-balham" // items bound to properties on the controller [gridOptions]="gridOptions" [columnDefs]="columnDefs" [showToolPanel]="showToolPanel" [rowData]="rowData" // boolean values 'turned on' animateRows pagination // simple values, not bound rowHeight="22" rowSelection="multiple" // event callbacks (modelUpdated)="onModelUpdated()" (cellClicked)="onCellClicked($event)" (cellDoubleClicked)="onCellDoubleClicked($event)"> </ag-grid-angular>

The above is all you need to get started using ag-Grid in a Angular application. Now would be a good time to try it in a simple app and get some data displaying and practice with some of the grid settings before moving onto the advanced features of cellRendering and custom filtering.

Child to Parent Communication

There are a variety of ways to manage component communication in Angular (shared service, local variables etc), but you often need a simple way to let a "parent" component know that something has happened on a "child" component. In this case the simplest route is to use the gridOptions.context to hold a reference to the parent, which the child can then access.

// in the parent component - the component that hosts ag-grid-angular and specifies which angular components to use in the grid constructor() { this.gridOptions = <GridOptions>{ context: { componentParent: this } }; this.gridOptions.rowData = this.createRowData(); this.gridOptions.columnDefs = this.createColumnDefs(); } // in the child component - the angular components created dynamically in the grid // the parent component can then be accessed as follows: this.params.context.componentParent

Note that although we've used componentParent as the property name here it can be anything - the main point is that you can use the context mechanism to share information between the components.

The "A Simple Example, using CellRenderers created from Angular Components" above illustrates this in the Child/Parent column:

Building & Bundling

There are many ways to build and/or bundle an Angular Application. In the Getting Started/Overview section we went through using Angular CLI to create an ag-Grid Angular application, but we also provide full working examples using either SystemJS, Webpack or Webpack 2 as part of the ag-grid-angular-example project on GitHub.

We document the main parts of these tools below, but please refer to the examples for more detail.

Creating Grids with Markup

You can create Grids either programatically (with pure JavaScript/Typescript/Components), or declare them via declaratively with markup.

The above section details how to specify the Grid itself. To declare columns you can specify them as follows:

Column Definition

<ag-grid-column headerName="Name" field="name" [width]="150"></ag-grid-column>

This example declares a simple Column Definition, specifying header name, field and width.

Setting Column Properties

There are some simple rules you should follow when setting column properties via Markup:

// string value
propertyName="String Value"
[propertyName]="'String Value'"
[propertyName]="{{Interpolated Value}}"

// boolean value
[propertyName]="{{Interpolated Value}}"

// numeric value
[propertyName]="Numeric Value"

// function value

Setting a Class or a Complex Value

You can set a Class or a Complex property in the following way:

// return a Class definition for a Filter [filter]="getSkillFilter()" private getSkillFilter():any { return SkillFilter; } // return an Object for filterParams [filterParams]="getCountryFilterParams()" private getCountryFilterParams():any { return { cellRenderer: this.countryCellRenderer, cellHeight: 20 } }

Grouped Column Definition

To specify a Grouped Column, you can nest a column defintion:

<ag-grid-column headerName="IT Skills"> <ag-grid-column headerName="Skills" [width]="125" [sortable]="false" [cellRenderer]="skillsCellRenderer" [filter]="getSkillFilter()"></ag-grid-column> <ag-grid-column headerName="Proficiency" field="proficiency" [width]="120" [cellRenderer]="percentCellRenderer" [filter]="getProficiencyFilter()"></ag-grid-column> </ag-grid-column>

In this example we have a parent Column of "IT Skills", with two child columns.

Example: Rich Grid using Markup

The example below shows the same rich grid as the example above, but with configuration done via Markup.

Cell Rendering & Cell Editing using Angular

It is possible to build cell renderers, cell editors and filters using Angular. Doing each of these is explained in the section on each.

Although it is possible to use Angular for your customisations of ag-Grid, it is not necessary. The grid will happily work with both Angular and non-Angular portions (eg cellRenderers in Angular or normal JavaScript).

Testing ag-Grid Angular Applications

Please see the dedicated testing section here.

Angular Grid Resources

  • Learn how to customize our Angular Grid in this guide.

  • Browse our Angular Grid page to discover all major benefits in using ag-Grid Angular.

  • Visit our blog to discover all our Angular content.