Vue Data Grid

Creating a Basic Grid

An introduction to the key concepts of AG Grid.

Overview

In this tutorial you will:

Once complete, you'll have an interactive grid, with custom components and formatted data - Try it out for yourself by sorting, filtering, resizing, selecting, or editing data in the grid:

Create a Basic Grid

Complete our Quick Start (or open the example below in CodeSandbox / Plunker) to start with a basic grid, comprised of:

Row Data: The data to be displayed.
Column Definition: Defines & controls grid columns.
Grid Component: The ag-grid-vue component, with Dimensions, CSS Theme, Row Data, and Column Definition attributes

Load New Data

As rowData is a managed property, any updates to its value will be reflected in the grid. Let's test this by fetching some data from an external server and updating rowData with the response.

// Fetch data when the component is mounted
onMounted(async () => {
 rowData.value = await fetchData();
});

const fetchData = async () => {
 const response = await fetch('https://www.ag-grid.com/example-assets/space-mission-data.json');
 return response.json();
};

Now that we're loading data from an external source, we can empty our rowData array (which will allow the grid to display a loading spinner whilst the data is being fetched) and update our colDefs to match the new dataset:

const App = {
 setup() {
   const rowData = ref([]);
   const colDefs = ref([
     { field: "mission" },
     { field: "company" },
     { field: "location" },
     { field: "date" },
     { field: "price" },
     { field: "successful" },
     { field: "rocket" }
   ]);
   // ...
 }
 // ...
}

When we run our application, we should see a grid with ~1,400 rows of new data, and new column headers to match:

Note: All Grid Option properties tagged as 'managed' are automatically updated when their value changes.

Configure Columns

Now that we have a basic grid with some arbitrary data, we can start to configure the grid with Column Properties.

Column Properties can be added to one or more columns to enable/disable column-specific features. Let's try this by adding the filter: true property to the 'mission' column:

const colDefs = ref([
 { field: "mission", filter: true },
 // ...
];

We should now be able to filter the 'mission' column - you can test this by filtering for the 'Apollo' missions:

Note: Column properties can be used to configure a wide-range of features; refer to our Column Properties page for a full list of features.

Default Column Definitions

The example above demonstrates how to configure a single column. To apply this configuration across all columns we can use Default Column Definitions instead. Let's make all of our columns filterable by creating a defaultColDef object with the property filter: true:

const App = {
 setup() {
   const defaultColDef = ref({
     filter: true
   });
   // ...
 }
 return {
   defaultColDef
   // ...
 };
 // ...
}

And then adding this to our ag-grid-vue component:

const App = {
 template:
   `
   <ag-grid-vue
     style="width: 100%; height: 100%"
     class="ag-theme-quartz-dark"
     :columnDefs="colDefs"
     :rowData="rowData"
     :defaultColDef="defaultColDef"
   >
   </ag-grid-vue>
   `,
 // ...
}

The grid should now allow filtering on all columns:

Note: Column Definitions take precedence over Default Column Definitions

Configure The Grid

So far we've covered creating a grid, updating the data within the grid, and configuring columns. This section introduces Grid Options, which control functionality that extends across both rows & columns, such as Pagination and Row Selection.

Grid Options are added directly to the ag-grid-vue component. Let's test this out by adding the :pagination="true" to the grid:

const App = {
 name: "App",
 template: 
   `
   <ag-grid-vue
     style="width: 100%; height: 100%"
     class="ag-theme-quartz-dark"
     :columnDefs="colDefs"
     :rowData="rowData"
     :defaultColDef="defaultColDef"
     :pagination="true"
   >
   </ag-grid-vue>
   `,
 //...
}

We should now see Pagination has been enabled on the grid:

Refer to our detailed Grid Options documentation for a full list of options.

Format Cell Values

The data supplied to the grid usually requires some degree of formatting. For basic text formatting we can use Value Formatters.

Value Formatters are basic functions which take the value of the cell, apply some basic formatting, and return a new value to be displayed by the grid. Let's try this by adding the valueFormatter property to our 'price' column and returning the formatted value:

const colDefs = ref([
  { field: "price", valueFormatter: (params) => { return '£' + params.value.toLocaleString(); } },
  // ...
]);

The grid should now show the formatted value in the 'price' column:

Note: Read our Value Formatter page for more information on formatting cell values

Custom Cell Components

Value Formatters are useful for basic formatting, but for more advanced use-cases we can use Cell Renderers instead.

Cell Renderers allow you to use your own components within cells. To use a custom component, set the cellRenderer prop on a column, with the value as the name of your component.

Let's try this by creating a new component to display the company logo in the 'company' column:

const CompanyLogoRenderer = {
 template:
   `
   <span style="display: flex; height: 100%; width: 100%; align-items: center;">
     <img :src="'https://www.ag-grid.com/example-assets/space-company-logos/' + cellValueLowerCase + '.png'" style="display: block; width: 25px; height: auto; max-height: 50%; margin-right: 12px; filter: brightness(1.1);" />
     <p style="text-overflow: ellipsis; overflow: hidden; white-space: nowrap;">{{ cellValue }}</p>
   </span>
   `,
 setup(props) {
   const cellValue = props.params.value;
   const cellValueLowerCase = cellValue.toLowerCase();
   return {
     cellValue,
     cellValueLowerCase
   };
 },
};

And then adding the cellRenderer property to the 'company' column:

const App = {
 components: {
   AgGridVue,
   companyLogoRenderer: CompanyLogoRenderer
 },
 setup() {
   const colDefs = ref([
     { field: "company", cellRenderer: "companyLogoRenderer" },
     // ...
   ]);
   // ...
 }
 // ...
}

Now, when we run the grid, we should see a company logo next to the name:

Note: Read our Cell Components page for more information on using custom components in cells

Handle Grid Events

In the last section of this tutorial we're going to hook into events raised by the grid using Grid Events.

To be notified of when an event is raised by the grid we need to use the relevant @[event-name] attribute on the ag-grid-vue component. Let's try this out by enabling cell editing with editable: true and hooking into the onCellValueChanged event to log the new value to the console:

const App = {
 template:
   `
   <ag-grid-vue
     ...
     @cell-value-changed="onCellValueChanged"
   >
   </ag-grid-vue>
   `,
 methods: {
   onCellValueChanged(event) {
     console.log(`New Cell Value: ${event.value}`);
   }
 },
 setup() {
   const defaultColDef = ref({
     editable: true,
     // ...
   });
   // ...
 }
 // ...
}

Now, when we click on a cell we should be able to edit it and see the new value logged to the console:

Refer to our Grid Events documentation for a full list of events raised by the grid

Test Your Knowledge

Let's put what you've learned so far into action by modifying the grid:

Enable Checkbox Selection on the 'mission' column
Hint: checkboxSelection is a Column Definition property
Enable multiple row selection
Hint: rowSelection is a Grid Option property
Log a message to the console when a row selection is changed
Hint: onSelectionChanged is a Grid Event
Format the Date column using .toLocaleDateString();
Hint: Use a valueFormatter on the 'Date' column to format its value
Add a Cell Renderer to display ticks and crosses in place of checkboxes on the 'Successful' column:
Hint: Use a cellRenderer on the 'successful' column

Once complete, your grid should look like the example below. If you're stuck, check out the source code to see how its done:

Summary

Congratulations! You've completed the tutorial and built your first grid. By now, you should be familiar with the key concepts of AG Grid:

Row Data: Your data, in JSON format, that you want the grid to display.
Column Definitions: Define your columns and control column-specific functionality, like sorting and filtering.
Default Column Definitions: Similar to Column Definitions, but applies configurations to all columns.
Grid Options: Configure functionality which extends across the entire grid.
Grid Events: Events raised by the grid, typically as a result of user interaction.
Value Formatters: Functions used for basic text formatting
Cell Renderers: Add your own components to cells

Next Steps

Browse our guides to dive into specific features of the grid: