Get Started with ag-Grid in Your Project
The Project Setup
Add ag-Grid to Your Project
We are going to load the necessary scripts and styles from the unpkg CDN. Add the following to the
The lines above import the
AgGrid component, the grid "structure" stylesheet (
ag-grid.css), and one of the available grid themes: (
The grid ships several different themes; pick one that matches your project design.
Now, let's instantiate a grid!
The variables above present two essential configuration properties of the grid - the column definitions (
columnDefs) and the data (
rowData). In our case, the column definitions contain three columns;
each column entry specifies the header label and the data field to be displayed in the body of the table.
The actual data is defined in the
rowData as an array of objects. Notice that the fields of the objects match the
field values in the
columnDefs configuration object.
DIV element is the DOM entry point of the grid. It sets the grid dimensions and specifies the grid's theme by setting the
ag-theme-balham. As you may have already noticed, the CSS class matches the name of CSS file we imported earlier.
Enable Sorting And Filtering
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 least/most expensive?
Well, enabling sorting in ag-Grid is actually quite simple - all you need to do is add
sortable to each column.
After adding the property, you should be able to sort the grid by clicking on the column headers. Clicking on a header toggles through ascending, descending and no-sort.
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 adding the
With this property set, the grid will display a small column menu icon when you hover the header. Pressing it will display a popup with filtering UI which lets you choose the kind of filter and the text that you want to filter by.
Fetch Remote Data
Notice that the actual data fetching is performed outside of the grid component - We are using the HTML5
Here, we replaced the
rowData assignment with a data fetch from a remote service. The remote data is the same as the one we initially had, so you should not notice any actual changes to the grid.
Notice that we also did something new - we accessed the grid Api instance through the
gridOptions.api. The api object exposes plethora of methods that allow us to implement complex scenarios with the grid.
Being a programmer is a hectic job. Just when we thought that we are done with our assignment, the manager shows up with a fresh set of requirements! It turned out that we need to allow the user to select certain rows from the grid and to mark them as flagged in the system. We will leave the flag toggle state and persistence to the backend team. On our side, we should enable the selection and, afterwards, to obtain the selected records and pass them with an API call to a remote service endpoint.
Fortunately, the above task is quite simple with ag-Grid. As you may have already guessed, it is just a matter of adding and changing couple of properties:
Great! Now the first column contains a checkbox that, when clicked, selects the row. The only thing we have to add is a button that gets the selected data and sends it to the server. To do this, we need the following change:
Well, we cheated a bit. Calling
alert is not exactly a call to our backend.
Hopefully you will forgive us this shortcut for the sake of keeping the article short and simple. Of course, you can substitute that bit with a real-world application logic after you are done with the tutorial.
What happened above? Several things:
- We added a button with an event handler;
- Inside the event handler, we accessed the grid API to get the currently selected grid row nodes;
- Afterwards, we extracted the row nodes' underlying data items and converted them to a string suitable to be presented to the user in an alert box.
In addition to filtering and sorting, grouping is another effective way for the user to make sense out of large amounts of data. In our case, the data is not that much. Let's switch to a slightly larger data set:
Now, let's use ag-grid-enterprise! Replace the ag-grid script reference in the
head with this one:
If everything is ok, you should see a message in the console that tells you there is no enterprise license key. You can ignore the message as we are trialing. In addition to that, the grid got a few UI improvements - a custom context menu and fancier column menu popup - feel free to look around:
Now, let's enable grouping! Change the configuration to this:
There we go! The grid now groups the data by
make, while listing the
model field value when expanded. Notice that grouping works with checkboxes as well - the
groupSelectsChildren property adds a group-level checkbox that selects/deselects all items in the group.
This is how the final code should look:
That's just scratching the surface, though. The grid has a lot more features to offer; the abilities to customize cells and headers with custom components allow for almost infinite possible configurations.