AG Grid Insert Row: APIs, Examples, and Row Model Tips

To insert a row in AG Grid’s Client-Side Row Model, call gridApi.applyTransaction({ add: [newRow], addIndex: 0 }); omit addIndex to add it at the end. The row must be an object containing the data fields your columns use, and the transaction changes the grid’s row model rather than automatically updating a separate application data array.

What “insert a row” means in AG Grid

AG Grid does not use the spreadsheet convention of inserting an empty row between fixed row numbers. It displays records supplied by your application or data source. Adding a row therefore usually means adding a new data object to the grid, then letting the grid apply sorting, filtering, grouping, and rendering rules to that record.

For the Client-Side Row Model, the transaction API is the direct way to add records while the grid is running. A transaction can add, update, or remove rows. It is useful when the grid already has data and you want to change a small part of it without replacing the complete dataset. If your application manages the data as state, changing that state and passing the updated array to the grid is another valid approach.

The right method depends on the row model. AG Grid’s Client-Side Row Model keeps the data in the browser; other models obtain rows from a server or datasource and have different update requirements. Identify the model before choosing an API.

Insert a row with a Client-Side transaction

Get the grid API from the grid’s ready callback, create an object matching your column data, and pass it in the transaction’s add array. This example inserts a record at index zero:

let gridApi;

const gridOptions = {
  columnDefs: [
    { field: 'id' },
    { field: 'product' },
    { field: 'quantity' }
  ],
  rowData: [],
  getRowId: params => String(params.data.id),
  onGridReady: params => {
    gridApi = params.api;
  }
};

function insertRow() {
  const newRow = {
    id: 'order-1042',
    product: 'Desk lamp',
    quantity: 1
  };

  gridApi.applyTransaction({
    add: [newRow],
    addIndex: 0
  });
}

In this example, addIndex: 0 requests insertion at the beginning of the row data. A transaction can add several records at once: place multiple objects in the add array. If no insertion index is supplied, the new records are added at the end of the row data.

getRowId is not required just to add a record, but it is a good practice for data that has a stable unique key. It lets AG Grid identify records consistently when data changes. Use an ID that is unique across the relevant dataset; adding a second record with an existing ID can lead to confusing update and selection behavior.

Choose between a transaction and replacing row data

A transaction is a good fit when the grid already contains data and you want to add one or a few records. It tells the grid exactly what changed. For example, an order-entry screen might add a new order after the user submits a form, while a live dashboard might receive a new event and append it to a list.

Replacing row data can be simpler when your application treats the complete array as the source of truth. In a framework such as React, create a new array with the record inserted and update the state that supplies the grid. Conceptually, the operation is: existing rows before the target index, then the new record, then the remaining rows. Do not mutate a state array in place; publish a new array so the framework can detect the change.

In plain JavaScript, the current grid API can accept replacement data through gridApi.setGridOption('rowData', nextRows). In React, update the state variable used for the grid’s rowData prop instead. When replacing data, stable row IDs help AG Grid reconcile records rather than treating every object as an unrelated row. A transaction is generally more focused, while replacing the array can make application-state flow easier to reason about.

One important distinction: applying a transaction to the grid does not, by itself, insert that record into a separate array your application still holds. If other parts of the application read or save that array, update the application’s state or data store as well. Otherwise, the grid can show a row that is missing from the data later submitted to your server.

Understand indexes, sorting, filtering, and grouping

An insertion index is not a promise that the new row will appear at that screen position under every grid configuration. It describes where the record is added to the row data used by the Client-Side Row Model. The displayed order may be determined by a sort, and a filter may hide the new record entirely. For example, adding a product at index zero does not force it above other products if the grid is sorted alphabetically by product name.

Grouping also affects where a record appears. If the new data belongs to a group, AG Grid displays it within that group according to the grid’s current row model and sort settings. A row that does not match an active filter will not appear until the filter changes or the data matches it. When troubleshooting, check the record in the underlying data and inspect sorting, filtering, and grouping before concluding that the transaction failed.

If the intended behavior is “show this new item first,” decide whether you mean first in the underlying data or first in the visible display. To make it visibly first while a sort is active, you may need to change the sort or include a sortable field that places the record where intended. Avoid relying on a row’s current displayed index as a permanent data position: displayed indexes can change when the user sorts or filters.

Insert from a form or add-row button

A common interface has an Add row button that opens a form. When the user submits valid values, construct a complete row object and call the appropriate update method. If a required field is missing, validate it before adding the object; the grid does not automatically know the business rules for a valid order, customer, or inventory item.

Collect values from the form and convert them to the expected data types. A quantity intended for arithmetic should be a number, not an unparsed text string.
Assign a unique ID before adding the object if the grid or application uses record IDs.
Choose whether the row belongs at the beginning, end, or a specific data index.
Update the grid and any application state or server-side store that must retain the record.
Give the user feedback if validation or saving fails; do not leave a row that appears saved when the server rejected it.

For a quick-entry workflow, some applications use a pinned top row as an input area. Pinned rows are visually separated from the ordinary row model; they are not simply normal records inserted at index zero. After the user enters values, the application typically validates them, creates a regular data object, adds that object to the actual data, and clears or resets the input row. This separation can be useful, but it requires explicit handling for validation and persistence.

Row-model differences

The Client-Side Row Model is the usual case for applyTransaction: the browser has the dataset and can process the added record locally. If you use a different row model, do not assume that the same call is the right way to create durable data.

With the Server-Side Row Model, records are supplied in server-managed stores. AG Grid provides server-side transactions, including applyServerSideTransaction, for supported configurations. The transaction needs to target the relevant store or route where applicable, and your server or application remains responsible for saving the record so it survives a refresh. Availability and behavior can depend on the store configuration and AG Grid version, so check the documentation for the version in use.

The Infinite Row Model loads blocks through a datasource and is designed for large, server-backed datasets. It does not use the Client-Side Row Model’s ordinary transaction workflow to insert into a complete browser-held dataset. Create or update the record in the backing source, then refresh or update the datasource as appropriate. The Viewport Row Model similarly relies on an external data source to manage the rows presented to the grid.

This is why an API call that appears correct can have no useful effect in the wrong setup: the row model may not own the complete data, or a server response may replace local changes. Confirm the configured row model and its update path before debugging the row object itself.

Common insertion problems

The new row is not visible: Confirm the transaction ran after the grid API was available, then check active filters, sorting, grouping, and pagination. The row may exist but be on another page or outside the current filter.
Values appear blank: Check that object property names match the column fields. A column defined with field: 'product' reads the product property; a value under productName will not populate it automatically.
Repeated additions behave strangely: Check that every record has a distinct stable ID when using getRowId. Do not reuse a constant ID for every new object.
The row appears in the grid but disappears later: Keep the application’s source array or server data in sync. A local grid transaction is not a substitute for saving to a backend.
The record appears in an unexpected position: Distinguish the insertion index from the visible order. Sorting, filtering, grouping, and pagination can all change where a row is shown.

For frequent streams of updates, AG Grid also offers asynchronous transaction processing for the Client-Side Row Model, which can batch work rather than immediately processing each change individually. It is more relevant to high-volume update flows than to a button that inserts one record. For ordinary form submission, a regular transaction is usually easier to follow.

Frequently Asked Questions

How do I add a row to the bottom of AG Grid?
For the Client-Side Row Model, call gridApi.applyTransaction({ add: [newRow] }) without an addIndex. The new record is added at the end of the row data, although sorting or grouping can change its displayed position.

How do I insert a row at the top of AG Grid?
Use gridApi.applyTransaction({ add: [newRow], addIndex: 0 }) with the Client-Side Row Model. This requests the beginning of the row data, not necessarily the top visible position when sorting, filtering, or grouping is active.

Can I insert a blank row?
You can add an object with empty or initial values, such as empty strings and a valid unique ID. Define what “blank” means for your application, and validate required fields before saving. An empty object may not provide the properties your columns or application logic expect.

Does applyTransaction update my original array?
Do not rely on it to update a separate array held by your application. Keep the application’s state or data store synchronized, or update the grid by supplying a new row-data array through your framework’s normal state flow.

Why can’t I use applyTransaction with my grid?
That method is intended for the Client-Side Row Model. Server-Side, Infinite, and Viewport configurations obtain data through other mechanisms and have their own update requirements. Check the configured row model and use its documented transaction or datasource workflow.

Try it: the Date Difference Calculator: days, months, years and weekdays between two dates, with the DATEDIF formulas.

More in How-to basics

Sources: Function behaviour and menu paths: Microsoft Support documentation for Excel. Method & sources

Spotted an error in this guide? Let us know.