Expand All

  Getting Started

  Reference

  Features

  Row Models

  Themes

  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

JavaScript Grid

Getting Started With ag-Grid and Plain JavaScript

This section documents how to get started with ag-Grid and JavaScript as quickly as possible. You will start off with a simple application and section by section add Grid features to the application ending up with a fully fledged application with ag-Grid at the heart of it.

Prerequisites

You will need the following build tools installed at a minimum:

  • Git: Please see Git for installation options

Scaffolding

To get started as quickly as possible we provide a "Seed" repo on Git that you can use. Let's clone this repo, install the dependencies and start it up:

# clone the ag-Grid React seed project git clone https://github.com/ag-grid/ag-grid-seed cd ag-grid-react-seed/javascript # Now either open index.html from the browser of your choice, or from the command line: # either Windows: start index.html # or OSX: open index.html

With those 2 commands you should now see the following application:

Great! A working Grid application in no time at all. Let's break down the application into it's main parts:

Row Data

At a minimum, a Grid requires row data & column definitions. Row data is provided to the grid as an array of JavaScript objects:

// row data [ {make: "Toyota", model: "Celica", price: 35000}, {make: "Ford", model: "Mondeo", price: 32000}, {make: "Porsche", model: "Boxter", price: 72000} ]

Here we have 3 rows of data, with make, model and price making up the data.

Column Definitions

To display this information we need to tell the Grid what data we're interested in. Let's define the three columns that match the data above:

// column definitions [ {headerName: "Make", field: "make"}, {headerName: "Model", field: "model"}, {headerName: "Price", field: "price"} ]

At a minimum a column definition needs a headerName - the column title to display - and a field - the data item to read off of from the row data. Here we're defining 3 columns, Make, Model and Price, each of which correspond to their lowercase equivalent in the row data above.

Grid Definition

Ok, so now we know how to define our row and column data - how do we define our actual Grid?

For a JavaScript application, you need to reference ag-Grid in your html file and provide a container (typically a div for ag-Grid to use::

<html> <head> <!-- reference the ag-Grid library--> <script src="https://cdnjs.cloudflare.com/ajax/libs/ag-grid/10.1.0/ag-grid.js"></script> <!-- our application code --> <script src="example.js"></script> </head> <body> <h1>Simple ag-Grid Example</h1> <!-- the div ag-Grid will use to render it's data --> <div id="myGrid" style="height: 115px;width:500px" class="ag-fresh"></div> </body> </html>

Here we're referencing version 10.1.0 from a CDN. You can use a CDN too, download ag-Grid (see More Details) or bundle it with a tool like Webpack.

We're also providing a div for ag-Grid to use here, along with a width and height. These could be any unit of course, including %.

Finally, we provide a theme for our Grid - the theme determines the Grids look and feel. Please see Themes for more information.

Next in our application, we define a gridOptions object that we will pass to the Grid - in this we declare the row and column information we want displayed:

// Grid Definition // let the grid know which columns and what data to use var gridOptions = { columnDefs: columnDefs, rowData: rowData }

Finally, we wait for the DOM to load and once ready find the container we want ag-Grid to use (as defined by the ID we provided above) and pass in the GridOptions we want to use:

// wait for the document to be loaded, otherwise, // ag-Grid will not find the div in the document. document.addEventListener("DOMContentLoaded", function() { // lookup the container we want the Grid to use var eGridDiv = document.querySelector('#myGrid'); // create the grid passing in the div to use together with the columns & data we want to use new agGrid.Grid(eGridDiv, gridOptions); });

The final setup looks like this:

We encourage you to experiment with the plunker above - try adding new rows of data for example or renaming column headers.

With this we have a simple application ready to go of course there is much more we can do - in the following sections we will build on this starting point.

Adding Features

Ok, great - so far so good. But wouldn't it be nice to be able to sort the data to help us see which car is the most expensive (or least!)?

Sorting

Adding sorting to our application is very easy - all you need to do is let the Grid know you want sorting to be enabled by setting a Grid property to true:

// Grid Definition // let the grid know which columns and what data to use var gridOptions = { columnDefs: columnDefs, rowData: rowData, // enable sorting enableSorting: true }

With a single property change we are now able to sort any column by clicking the column header (you can keep clicking and it will cycle through ascending, descending and no sort). Note that in this example we're sorting by Price in ascending order (indicated by the up arrow):

Filtering

Our application doesn't have too many rows, so it's fairly easy to find data. But it's easy to imagine how a real-world application may have hundreds (or even hundreds of thousands!) or rows, with many columns. In a data set like this filtering is your friend.

As with sorting, enabling filtering is as easy as setting a single property in our Grid definition:

// Grid Definition // let the grid know which columns and what data to use var gridOptions = { columnDefs: columnDefs, rowData: rowData, enableSorting: true, // enable filtering enableFilter: true }

With the enableFilter property set we are now able to filter any column by clicking the column header "hamburger" to the right of a column (visible when hovered over). Note that in this example we're filtering the Model column by the text Celica - only the row with Celica is shown now.

Summary

We've only scratched the surface with what you can do with the Grid - please refer to the full set of features on the left hand navigation for an idea of what's on offer, but below we show a feature rich example:

This example makes use of custom cell renderer's to show data in a visually friendly way, demonstrates column grouping as well as using JavaScript Components in the header. And even this rich example is only scratching the surface - we've only just gotten started with with ag-Grid can do!

Please read the More Details section next to get a deeper understanding of how to use ag-Grid and React, as well as the options in installing dependencies and accessing the Enterprise Features.