Expand All

  Getting Started

  Interfacing

  Features

  Row Models

  Themes

  Components

  Examples

  Third Party

Misc

Github stars make projects look great. Please help, donate a star, it's free.
Get informed on releases and other ag-Grid news only - never spam.
Follow on Twitter

Cell Editing

cellRenderers and cellEditors, the former for showing the data, the latter for editing the data. If your application is for showing data only, such as a reporting application, then you will not need to use cellEditors. If you are editing your data like a spreadsheet, then cellEditors are going to be your best friend as you build your application using ag-Grid.

Use cellEditors to provide editing functionality to your data through the grid that ties in with the grid navigation, refresh and general data management.

You configure cellEditors as part of the column definition and can be one of the following:

  • component: The grid will call 'new' on the provided class and treat the object as a component, using lifecycle methods.
  • string: The cellEditor is looked up from the provided cellEditors. Use this if you want to use a built in editor.

Default Editing

To get simple string editing, you do not need to provide an editor. The grid by default allows simple string editing on cells. The default editor is used if you have colDef.editable=true but do not provide a cellEditor.

Start Editing

If you have colDef.editable=true set for a column then editing will start upon any of the following: Editing can start in the following ways:

  • Edit Key Pressed: One of the following is pressed: Enter, F2, Backspace, Delete. If this happens then params.keyPress will contain the key code of the key that started the edit. The default editor will clear the contents of the cell if Backspace or Delete are pressed.
  • Printable Key Pressed: Any of the following characters are pressed: "qwertyuiopasdfghjklzxcvbnmQWERTYUIOPASDFGHJKLZXCVBNM1234567890!"£$%^&*()_+-=[];\'#,./\|<>?:@~{}"
    If this happens then params.charPress will contain the character that started the edit. The default editor places this character into the edit field so that the user experience is they are typing into the cell.
  • Mouse Double Click: If the mouse is double clicked. There is a grid property singleClickEdit that will allow single click to start editing instead of double click. Another property suppressClickEdit will prevent both single click and double click from starting the edit - use this if you want to have your own way of starting editing only, such as clicking a button in your custom cellRenderer.
  • api.startEditingCell(): If you call startEditingCell() on the grid API

Stop / End Editing

The grid will stop editing when any of the following happen:

  • Callback stopEditing: The callback stopEditing (from the params above) gets called by the editor. This is how your cellEditor informs the grid to stop editing.
  • Other Cell Focus: If focus in the grid goes to another cell, the editing will stop.
  • Enter Key Down: If the grid receives an 'Enter' key press event on the cell. If you do NOT want to stop editing when Enter is pressed, then listen for the event and stop propagation so the grid does not act on the event.
  • Escape Key Down: Similar to Enter, if Escape key is pressed, editing will stop. Unlike Enter, Escape action will not take the new value, it will discard changes.
  • Tab Key Down: Editing will stop, accepting changes, and editing will move to the next cell, or the previous cell if 'shift' is also pressed.
  • Navigation Key Down: Editing will stop, accepting changes, and editing will move to the next cell in the direction of the navigation key.
  • Popup Editor Closed: If using popup editor, the popup is configured to close if you click outside the editor. Closing the popup triggers the grid to stop editing.
  • gridApi.stopEditing(): If you call stopEditing() on the grid API.

An editor can be in a popup or in cell.

In Cell

In Cell editing means the contents of the cell will be cleared and the editor will appear inside the cell. The editor will be constrained to the boundaries of the cell, if it is larger that the provided area it will be clipped. When editing is finished, the editor will be removed and the renderer will be placed back inside the cell again.

Popup

If you want your editor to appear in a popup (such as a dropdown list), then you can have it appear in a popup. The popup will behave like a menu in that any mouse interaction outside of the popup will close the popup. The popup will appear over the cell, however it will not change the contents of the cell. Behind the popup the cell will remain intact until after editing is finished which will result in the cell being refreshed.

From a lifecycle and behaviour point of view, 'in cell' and 'popup' have no impact on the editor. So you can create a cellEditor and change this property and observe how your editor behaves in each way.

To have an editor appear in a popup, have the isPopup() method return true. If you want editing to be done within a cell, either return false or don't provide this method at all.

Tab Navigation

While editing, if you hit tab, the editing will stop on the current cell and start on the next cell. If you hold down shift+tab, the same will happen except the previous cell will start editing rather than the next. This is in line with editing data in Excel.

The next and previous cells can also be navigated using the API functions api.tabToNextCell() and api.tabToPreviousCell(). Both of these methods will return true if the navigation was successful, otherwise false.

Provided cellEditors

The grid, out of the box, comes with the following editors:

  • text: Simple text editor that uses standard HTML Input. This is the default.
  • select: Simple editor that uses standard HTML Select.
  • popupText: Same as 'text' but as popup.
  • popupSelect: Same as 'select' but as popup.
  • largeText: - A text popup that for inputting larger, multi-line text.
  • richSelect (ag-Grid-Enterprise only): - A rich select popup that uses row virtualisation

We have found the standard HTML 'select' to behave odd when in the grid. This is because the browser doesn't have a great API for opening and closing the select's popup. We advise you don't use it unless you have to - that is we advise against 'select' and 'popupSelect' as they give poor user experience, especially if using keyboard navigation. If using ag-Grid Enterprise, then you should use the provided richSelect.

The default text cellEditor takes no parameters. The select cellEditor takes a list of values from which the user can select. The example below shows configuring the select cellEditor.

colDef.cellEditor = 'select';
colDef.cellEditorParams = {
    values: ['English', 'Spanish', 'French', 'Portuguese', '(other)']
}

If you have many instances of a grid, you must register the cellEditors with each one.

Callback: New Value Handlers

A newValueHandler is the inverse of a valueGetter. If you want to set the value into the data yourself and not use the field, then use the newValueHandler. Use a newValueHandler if:

  1. A field value alone cannot be used, eg you want to place the new value into an array at a particular index.
  2. You want to do some formatting to the value before placing it.

// this does exactly what a field does, no difference,
// but provided to demonstrate the equivalent of just using field
colDef.newValueHandler = function(params) {
    var field = params.colDef.field;
    var data = params.data;
    var value = params.newValue;
    data[field] = value;
}

// this one does some formatting first, and doesn't use the field
colDef.newValueHandler = function(params) {
    var data = params.data;
    var value = params.newValue;
    // change the value, maybe we want it in upper case
    var value = formatTheValueSomehow(value);
    data.iAmNotUsingTheField = value;
}

newValueHandler is provided a params object with attributes:
node: The grid node in question.
data: The row data in question.
oldValue: If 'field' is in the column definition, contains the value in the data before the edit.
newValue: The string value entered into the default editor.
rowIndex: The index of the virtualised row.
colDef: The column definition.
context: The context as set in the gridOptions.
api: A reference to the ag-Grid API.

Event: Cell Value Changed

After a cell has been changed with default editing (ie not your own custom cell renderer), then cellValueChanged event is fired. You can listen for this event in the normal way, or additionally you can add a onCellValueChanged() callback to the colDef. This is used if your application needs to do something after a value has been changed.

The cellValueChanged event contains the same parameters as newValueHandler with one difference, the newValue. If 'field' is in the column definition, the newValue contains the value in the data after the edit. So for example, if the onCellValueChanged converts the provided string value into a number, then newValue for newValueHandler will have the string, and newValue for onCellValueChanged will have the number.

Editing API

There are two api methods for editing, startEditingCell() and stopEditing(params).

api.startEditingCell(params)
Starts editing the provided cell. If another cell is editing, the editing will be stopped in that other cell. Parameters are as follows:

  • rowIndex: The row index of the row to start editing.
  • colKey: The column key of the column to start editing.
  • keyPress, charPress: The keyPress and charPress that are passed to the cellEditor

api.stopEditing(cancel)
If the grid is editing this will stop editing.

Pass true to cancel editing, i.e. revert any changes.

Start / Stop Editing Events

The following events are fired as editing starts and stops:

  • cellEditingStarted: editing has started on a cell.
  • cellEditingStopped: editing has stopped on a row.
  • rowEditingStarted: editing has started on a row. Only for full row editing.
  • rowEditingStopped: editing has stopped on a row. Only for full row editing.

Cell Editing Example

The example below illustrates different parts of the editing API using the buttons at the top.

Datepicker Cell Editing Example

The example below illustrates:

  • 'Date' column uses a Component cell editor that allows you to pick a date using jQuery UI Datepicker.

Full Row Editing

Full row editing is for when you want all cells in the row to become editable at the same time. This gives the impression to the user that the record the row represents is getting edited.

To enable full row editing, set the grid option editType = 'fullRow'.

If using custom cell editors, the cell editors will work in the exact same way with the following additions:

  • focusIn: If your cellEditor has a focusIn method, it will get called when the user tabs into the cell. This should be used to put the focus on the particular item to be focused, eg the textfield within your cellEditor.
  • focusOut: If your cellEditor has a focusOut method, it will get called when the user tabs out of the cell. No intended use for this, is just there to compliment the focusIn method, maybe you will have a reason to use it.
  • Events: When a row stops editing, the cellValueChanged event gets called for each column and rowValueChanged gets called once for the row.

Full Row Edit and Popup Editors

Full row editing is not compatible with popup editors. This is because a) the grid would look confusing to pop up an editor for each cell in the row at the same time and b) the complexity of navigation and popup is almost impossible to model - thus the grid and your application code would be to messy and very error prone. If you are using full row edit, then you are blocked from using popup editors.

This does not mean that you cannot show a popup from your 'in cell' editor - you are free to do that - however the responsibility of showing and hiding the popup belongs with your editor. You may want to use the grids focus events to hide the popups when the user tabs or clicks out of the cell.

Full Row Edit Example

The example below shows full row editing. In addition to standard full row editing, the following should also be noted:

  • The 'Price' column has a custom editor demonstrating how you should implement the 'focusIn' method. Both focusIn and focusOut for this editor are logged to the console.
  • The 'Suppress Navigable' column is not navigable using tab. In other words, when tabbing around the grid, you cannot tab onto this cel.
  • The 'Not Editable' column is not editable, so when the row goes into edit mode, this column is not impacted. Also when editing, this column is not navigated to when tabbing.
  • The button will start editing line two. It uses the api to start editing a cell, however the result is the whole row will become editable starting with the specified cell.
  • cellValueChanged and rowValueChanged events are logged to console.
  • The CSS class ag-row-editing changes the background color to highlight the editing row.

Group Editing

By default, the grid does not let you edit group rows. This is to cater for the scenario where groups are aggregations of the children (ie a group rows values could be the sum of the children, so editing the group doesn't make sense).

In other scenarios, editing groups does make sense. For example if implementing a file explorer, editing a folder name or owner does make sense in isolation to the contained files. Thus to cater for this, you can enable editing of groups with the property enableGroupEdit=true.

The example below shows using enableGroupEdit=true along with tree data to allow editing of group data.

Single Click, Double Click, No Click Editing

Double Click Editing

The default is for the grid to enter editing when you double click on a cell.

Single Click Editing

To change the default so that a single click starts editing, set the property singleClickEdit=true. This is useful when you want a cell to enter edit mode as soon as you click on it, similar to the experience you get when inside Excel.

No Click Editing

To change the default so that neither single or double click starts editing, set the property suppressClickEdit=true. This is useful when you want to start the editing in another way, such as including a button in your cellRenderer.

Single Click and No Click Example

Stop Editing When Grid Loses Focus

By default, the grid will not stop editing the currently editing cell when the grid loses focus. This can be bad if, for example, you have a save button, and you need the grid to stop editing before you execute your save function (eg you want to make sure the edit is saved into the grids state).

If you want the grid to stop editing when focus leaves, set the grid property stopEditingWhenGridLosesFocus=true.

By default, the grid not stop editing if you focus outside. The default is good for custom popup cell editors as these can have the focus leave the grid (eg if using a popup calendar widget). This would be bad as the grid would stop editing as soon as your external popup appeared.

The example below shows the editing with stopEditingWhenGridLosesFocus=true. Notice the following:

  • Double click to start editing 'Age', then click outside the grid (on the 'Dummy Save' button, or the dummy text field) and the grid will stop editing.
  • Double click to start editing 'Year', a custom popup editor appears, you can click anywhere on the popup editor, but once you click outside the editor, the popup closes.

Cell Editing can also be done via Cell Editor Components - please see Cell Editor Components for more information.