Expand All

  Getting Started

  Interfacing

  Features

  Row Models

  Themes

  Components

  Examples

Misc

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

Next Steps

ag-Grid Angular Features

Please use the github project ag-grid-angular for feedback or issue reporting around ag-Grid's support for Angular. Full Working Examples can be found in the Angular Examples section.

 

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.

Dependencies

In your package.json file, specify dependency on ag-grid AND ag-grid-angular. The ag-grid package contains the core ag-grid engine and the ag-grid-angular contains the Angular component.

"dependencies": {
    ...
    "ag-grid": "8.1.x",
    "ag-grid-angular": "8.1.x"
}
The major and minor versions should match. Every time a new major or minor version of ag-Grid is released, the component will also be released. However for patch versions, the component will not be released.

You will then be able to access ag-Grid inside your application:

import {AgGridModule} from 'ag-grid-angular/main';

Which you can then use as a dependency inside your module:

@NgModule({
    imports: [
        BrowserModule,
        AgGridModule.withComponents([...optional Angular Components to be used in the grid....]]),
        ...
})

You will need to include the CSS for ag-Grid, either directly inside your html page, or as part of creating your bundle if bundling. The following shows referencing the css from your web page:

<link href="node_modules/ag-grid/dist/styles/ag-grid.css" rel="stylesheet" />
<link href="node_modules/ag-grid/dist/styles/theme-fresh.css" rel="stylesheet" />

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 API's are attributes on the controller).
  • Changing Properties: When a property changes value, AngularJS 1.x automatically passes the new value onto the grid. This is used in the following locations in the "feature rich grid example" above:
    a) The 'quickFilter' on the top right updates the quick filter of the grid. b) The 'Show Tool Panel' checkbox has it's 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 it's 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 on you cannot safely 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 cellRenderers, cellEditors 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-fresh"

    // items bound to properties on the controller
    [gridOptions]="gridOptions"
    [columnDefs]="columnDefs"
    [showToolPanel]="showToolPanel"
    [rowData]="rowData"

    // boolean values 'turned on'
    enableColResize
    enableSorting
    enableFilter

    // 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.

ag-Grid Angular Examples

Example: Rich Grid

The example below shows a rich configuration of ag-Grid.

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}}"
[propertyName]="functionCallReturningAString()"

// boolean value
[propertyName]="true|false"
[propertyName]="{{Interpolated Value}}"
[propertyName]="functionCallReturningABoolean()"

// numeric value
[propertyName]="Numeric Value"
[propertyName]="functionCallReturningANumber()"

// function value
[propertyName]="functionName"
[propertyName]="functionCallReturningAFunction()"

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" [suppressSorting]="true" [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 cellRenderers, cellEditors 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). If you do use Angular, be aware that you are adding an extra layer of indirection into ag-Grid. ag-Grid's internal framework is already highly tuned to work incredibly fast and does not require Angular or anything else to make it faster. If you are looking for a lightning fast grid, even if you are using Angular and the ag-grid-angular component, consider using plain ag-Grid Components (as explained on the pages for rendering etc) inside ag-Grid instead of creating Angular counterparts.

  Installing ag-Grid-Enterprise

Download ag-Grid-Enterprise

Bower
bower install ag-grid-enterprise
NPM
npm install ag-grid-enterprise
Github
Download from Github

Referencing ag-Grid-Enterprise

In your application, before instantiating the grid, you need to reference the included ag-grid-enterprise dependency:

import {AgGridModule} from "ag-grid-angular/main";
import "ag-grid-enterprise";
...other dependencies

Next Steps...

Now you can go to interfacing to learn about accessing all the features of the grid, or take a look at more detailed documentation around specifics like cellRenderers, cellEditors and filters using Angular.

Framework Projects

If using Angular, VueJS, React or Aurelia then you will also need to reference the additional ag-Grid project for that framework. Details are provided the documentation for those frameworks.

Bundled vs CommonJS & Frameworks Summary

If you want to use the Angular or React component of ag-Grid, then you have to use the commonjs distribution (not the bundled). You will also need to include the additional ag-Grid project for these components.

If you are using the plain Javascript, Angular 1 or Web Components version of ag-Grid, you can use the bundled version or the commonjs version.

The table below summarises these details.

Framework Works with Bundled Works with CommonJS Extra Project
Pure JavaScript Yes Yes -
React No Yes ag-grid-react
Angular 1 Yes Yes -
Angular No Yes ag-grid-angular
VueJS No Yes ag-grid-vue
Aurelia No Yes ag-grid-aurelia
Web Components Yes Yes -

Warning: if you are using the bundled version of the grid (/dist/ag-grid-js) then you must specify this directly, the main files specified in package.json and bower.json point to the commonjs versions of ag-Grid.

List of Loading / Building Examples

Below is a list of the examples demonstrating the different build tools, loading mechanisms and frameworks. You may not see the exact stack you want, but you can grab information from all the examples. Eg you might want to program React and Typescript, below you can see examples of React and Typescript, just not together.

Choosing a Framework and What Next

ag-Grid does not favor any framework. It's agnostic. It doesn't have a preference for what framework you use. ag-Grid supports 7 flavours: Angular, AngularJS 1.x, React, VueJS, Aurelia, Web Components and Native Javascript. Every ag-Grid feature is fully available in each framework, there is no bias. You choose which framework you want. So continue now to the section on the framework you are interested in, then jump to the details of how to use the grid.