Expand All

  Getting Started

  Reference

  Features

  Row Models

  Themes new

  Components

  Examples

  Third Party

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

Angular Angular Grid

This page details how to set up ag-Grid inside and Angular 1.x application.

Download ag-Grid

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

Referencing ag-Grid

ag-Grid is distributed as both a self contained bundle (that places ag-Grid on the global scope) and also via a CommonJS package.

Using the bundled version is the quickest way to get going - reference this version in your HTML file is all you need to do.

You also need to provide a block (a div is the most common) element for the Grid to use - assign it an ID which you can then use later when instantiating the Grid.

<html> <head> <script src="path-to-ag-grid-/ag-grid.js"></script> <script src="example1.js"></script> </head> <body> <div id="myGrid" style="height: 100%;" class="ag-theme-fresh"></div> </body> </html>

When the ag-Grid script loads, it does not register with AngularJS 1.x. This is because AngularJS 1.x is an optional part of ag-Grid and you need to tell ag-Grid you want to use it.

ag-Grid Bundle Types

There are four bundle files in the distribution:

  • dist/ag-grid.js -> standard bundle containing JavaScript and CSS
  • dist/ag-grid.min.js -> minified bundle containing JavaScript and CSS
  • dist/ag-grid.noStyle.js -> standard bundle containing JavaScript without CSS
  • dist/ag-grid.min.noStyle.js -> minified bundle containing JavaScript without CSS

CommonJS

To use CommonJS, it's best to download the packages via NPM and then either require (ECMA 5) or import (ECMA 6) them into your project.

// ECMA 5 - using nodes require() method var AgGrid = require('ag-grid'); // ECMA 6 - using the system import method import {Grid} from 'ag-grid/main';

Download ag-Grid-Enterprise

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

Referencing ag-Grid-Enterprise

ag-Grid-Enterprise is also distributed as both a self contained bundle and also via a CommonJS package.

As with the ag-Grid example, all we need to do is reference the ag-grid-enterprise dependency and we're good to go:

<html> <head> <script src="path-to-ag-grid-enterprise/ag-grid-enterprise.js"></script> <script src="example1.js"></script> </head> <body> <div id="myGrid" style="height: 100%;" class="ag-theme-fresh"></div> </body> </html> Self Contained Bundles

Do not include both ag-Grid and ag-Grid-Enterprise self contained bundles. The ag-Grid-Enterprise contains ag-Grid.

The creation of the Grid would be the same as the ag-Grid example above.

ag-Grid Enterprise Bundle Types

Again similar to ag-Grid, ag-Grid-Enterprise has 4 bundles:

  • dist/ag-grid-enterprise.js -> standard bundle containing JavaScript and CSS
  • dist/ag-grid-enterprise.min.js -> minified bundle containing JavaScript and CSS
  • dist/ag-grid-enterprise.noStyle.js -> standard bundle containing JavaScript without CSS
  • dist/ag-grid-enterprise.min.noStyle.js -> minified bundle containing JavaScript without CSS

Even if you are using React, AngularJS 1.x, Angular, VueJS or Web Components, the above is all you need to do. Any grid you create will be an enterprise grid once you load the library.

CommonJS

If using CommonJS, you one need to include ag-Grid-Enterprise into your project. You do not need to execute any code inside it. When ag-Grid-Enterprise loads, it will register with ag-Grid such that the enterprise features are available when you use ag-Grid.

// ECMA 5 - using nodes require() method var AgGrid = require('ag-grid'); // only include this line if you want to use ag-grid-enterprise require('ag-grid-enterprise'); // ECMA 6 - using the system import method import {Grid} from 'ag-grid/main'; // only include this line if you want to use ag-grid-enterprise import 'ag-grid-enterprise/main';

Creating the AngularJS 1.x Module

Include ag-Grid as a dependency of your module like this:

// if you're using ag-Grid-Enterprise, you'll need to provide the License Key before doing anything else // not necessary if you're just using ag-Grid agGrid.LicenseManager.setLicenseKey("your license key goes here"); // get ag-Grid to create an Angular module and register the ag-Grid directive agGrid.initialiseAgGridWithAngular1(angular); // create your module with ag-Grid as a dependency var module = angular.module("example", ["agGrid"]);

ag-Grid Div

To include a grid in your html, add the ag-grid attribute to a div. The value of the div should be the provided grid options on the scope.

It is also usual to provide a styling theme to the grid. Three themes come with the grid, ag-theme-fresh, ag-theme-dark and ag-theme-blue. Each one is set by applying the corresponding class of the same name to the div. In the example, ag-theme-fresh is used.

You must provide width and height to your grid. The grid is programmed to fill the width and height you give it.

<div ag-grid="gridOptions" class="ag-theme-fresh" style="height: 100%;"></div>

(note: a div by default has 100% width, so the width is not specified explicitly above).

Grid Options

The grid options provide ag-Grid with the details needed to render. At a minimum you should provide the columns (columnDefs) and the rows (rowData).

Basic AngularJS 1.x Example

Components

When using Components within an AngularJS 1.x application you need to manage both the scope yourself - the Grid does not provide the scope to the Components nor will it destroy it.

You need to ensure provide an appropriate scope to the Components and ensure you delete it when the component is destroyed.

angularCompileRows, angularCompileFilters and angularCompileHeaders are not supported within Components.

Destroy

You do not need to manually clean up the grid. The grid ties in with the AngularJS 1.x lifecycle and releases all resources when the directive is destroyed.

Angular Compiling

Angular 1.x is great. It allows us to build large end-to-end single page web apps with relative ease. However the author of ag-Grid is of the opinion that not everything should be built in Angular. Angular 1.x does come with a disadvantage, it can slow things down. ag-Grid does not use Angular 1.x (or any other framework) underneath the hood, it is all blazing fast raw Javascript.

But maybe you are not worried about performance. Maybe you are not displaying that many rows and columns. And maybe you want to provide your own cell renderers and use Angular here. For whatever reason, it is possible to turn Angular on for Angular version 1.x.

When Angular is turned on in ag-Grid, every time a row is inserted, a new child Angular Scope is created for that row. This scope gets the row attached to it so it's available to any Angular logic inside the cell.

Each cell within the row does not get a new child scope. So if placing item inside the child scope for the row, be aware that it is shared across all cells for that row. If you want a cell to have it's own private scope, consider using a directive for the renderer that will introduce a new scope.

Turn On Angular Compile

Angular compiling is turned on by setting the grid options attribute angularCompileRows to true.

  • angularCompileRows: Whether to compile the rows for Angular.
  • angularCompileFilters: Whether to compile provided custom filters.
  • angularCompileHeaders: Whether to compile the customer headers for AngularJS 1.x.

The default is always to have Angular compiling off for performance reasons.

Example using Angular Compile

Below then uses three columns rendered using custom Angular renderers.

  • Athlete: Uses simple binding to display text.
  • Age: Uses simple binding to display a button, with a button click event using ng-click.
  • Country: Uses a custom Angular directive to display the country.
When scrolling the example above up and down, the cells rendered using Angular are blank initially, and filled in during the next Angular digest cycle. This behaviour the author has observed in other Angular grid implementations. This is another reason why the author prefers non-Angular rendering for large grids.

Cell Templates

Cell Templates allow you to specify templates to use to render your cells. This is handy if you want to put JavaScript markup with AngularJS 1.x bindings as the cells. Cell templates are specified in the column definition by providing a template as a string or a templateUrl to load the template from the server.

If using templateUrl, then the html is cached. The server is only hit once per template and it is reused.

The example below uses cell templates for the first three columns.

  • Col 1 - The first column uses a static template. Pretty pointless as you can't change the content between rows.
  • Col 2 - The second column uses an inline template. AngularJS 1.x is then used to fetch the content from the scope via ng-bind.
  • Col 3 - The third column is similar to the second, with the difference that it loads the template from the server.

In the example, as you scroll up and down, the redraw on the AngularJS 1.x columns has a lag. This is waiting for the AngularJS 1.x digest cycle to kick in to populate the values into these rows.

Angular 1.x and ag-Grid Components

ag-Grid does not provide direct support for it's components and AngularJS 1.x. If you want to put custom AngularJS 1.x components into ag-Grid, follow the instructions for plain JavaScript component. You will then need to manage creating and destroying child scopes yourself inside the init() and destroy() methods.

angularCompileRows, angularCompileFilters and angularCompileHeaders are not supported within Components.

Events & Digest Cycle

For AngularJS 1.x - ag-Grid does not not fire events inside an Angular JS digest cycle. This is done on purpose for performance reasons, as there are many events fired, even if you don't listen to them. Firing the digest cycle for each one would kill performance. So you may want to $scope.$apply() after you handle the event.

Next Steps...

Now you can go to interfacing to learn about accessing all the features of the grid.