# Cell and row editing

Cell editing changes one value immediately; full-row editing commits multiple fields as one row operation. editor specifies the input UI, while editable controls write access.

Canonical: https://grid.syidax.com/docs/features/cell-editing/

<a id="understand"></a>

## How it works and when to use it

Define stored value types for number, date, select, and checkbox editors. Parsers convert input into values, and validation checks allowed limits.

In the code, grid is the Grid element prepared in the installation chapter. Check each example's data and settings, and implement the app functions and server endpoints for your project.

- [Installation and integration · Shared sample data](https://grid.syidax.com/docs/guides/getting-started.md)

<a id="example-1"></a>

## Example 1. Number and basic Select editing

Enter quantities as nonnegative numbers and statuses from a predefined list.

```javascript
grid.columnDefs = [
  { field: 'quantity', editable: true, editor: 'number', min: 0, step: 1 },
  { field: 'status', editable: true, editor: 'select', options: [
    { value: 'open', label: 'In progress' }, { value: 'done', label: 'Complete' }
  ] }
];
```

Verify the result: Distinguish display labels from stored values. Selecting Complete stores done in the source data.

<a id="example-2"></a>

## Example 2. Commit a row

Start editing a displayed order, temporarily change its quantity, then commit.

```javascript
const started = await grid.startRowEdit('ORD-0001');
if (started) {
  await grid.stageRowEditCell('quantity', 25);
  console.log(await grid.stopRowEdit('commit'));
}
```

Verify the result: If starting row editing is rejected, do not proceed. Read the commit report to determine what was actually applied.

<a id="example-3"></a>

## Example 3. Cancel editing and subscribe to results

Discard uncommitted values when users cancel, and use only actual change results for saving.

```javascript
await grid.stopRowEdit('cancel');
grid.addEventListener('cellValueChanged', event => console.log(event.detail));
grid.addEventListener('rowValueChanged', event => console.log(event.detail));
```

Verify the result: Assign clear roles to cell-change and full-row commit events so they do not cause duplicate server saves.

<a id="pitfalls"></a>

## Combining features and troubleshooting

Group headings, detail rows, and unloaded placeholders differ from editable data rows. You need a stable ID and editable columns.

Validation failure may leave the editing session active. Clicking Commit alone is not a reason to display a success message.

<a id="related-api"></a>

## APIs used by this feature

- [editType](https://grid.syidax.com/docs/options/editType.md) — Selects single-cell editing or editing multiple cells as one row operation.
- [cellEditor](https://grid.syidax.com/docs/columns/cellEditor.md) — Declares a custom cell editor. Use editor to select a built-in editor type.
- [editable](https://grid.syidax.com/docs/columns/editable.md) — Allows editing this column. Row permissions and validation still apply.
- [editor](https://grid.syidax.com/docs/columns/editor.md) — Built-in editor type, such as text, number, date, select, or checkbox.
- [valueParser](https://grid.syidax.com/docs/columns/valueParser.md) — Converts input text to the stored type, for example by normalizing numbers or dates.
- [valueSetter](https://grid.syidax.com/docs/columns/valueSetter.md) — Custom logic for writing a converted value into the source row. Follow the return contract indicating whether a change occurred.
- [options](https://grid.syidax.com/docs/columns/options.md) — Values and display labels for select editors. Individual options can be disabled.
- [min](https://grid.syidax.com/docs/columns/min.md) — Minimum allowed value for number or date editing.
- [max](https://grid.syidax.com/docs/columns/max.md) — Maximum allowed value for number or date editing.
- [step](https://grid.syidax.com/docs/columns/step.md) — Increment/decrement step for numeric input.
- [decimals](https://grid.syidax.com/docs/columns/decimals.md) — Decimal precision for numeric editing.
- [nullable](https://grid.syidax.com/docs/columns/nullable.md) — Whether null is accepted as an edited value.
- [allowEmpty](https://grid.syidax.com/docs/columns/allowEmpty.md) — Whether empty values are allowed while editing. Review together with required-value validation.
- [storeAs](https://grid.syidax.com/docs/columns/storeAs.md) — Whether date edits are stored as Date objects or ISO strings.
- [rows](https://grid.syidax.com/docs/columns/rows.md) — Default visible line count for a multiline text editor.
- [maxRows](https://grid.syidax.com/docs/columns/maxRows.md) — Maximum line count to which a multiline editor can grow.
- [cols](https://grid.syidax.com/docs/columns/cols.md) — Display width basis for a multiline text editor.
- [maxLength](https://grid.syidax.com/docs/columns/maxLength.md) — Maximum text editing length.
- [startRowEdit](https://grid.syidax.com/docs/methods/startRowEdit.md) — Starts full-row editing for a row ID.
- [stopRowEdit](https://grid.syidax.com/docs/methods/stopRowEdit.md) — Commits or cancels current row editing and returns a report.
- [stageRowEditCell](https://grid.syidax.com/docs/methods/stageRowEditCell.md) — Sets a pending value for a column in the row currently being edited.
- [getActiveEditTransaction](https://grid.syidax.com/docs/methods/getActiveEditTransaction.md) — Reads the active cell editing transaction, or null when not editing.
- [commitActiveEdit](https://grid.syidax.com/docs/methods/commitActiveEdit.md) — Commits current cell editing and returns success.
- [cancelActiveEdit](https://grid.syidax.com/docs/methods/cancelActiveEdit.md) — Cancels current cell editing and returns whether it ran.
- [getCellEditorInstance](https://grid.syidax.com/docs/methods/getCellEditorInstance.md) — Reads the mounted cell editor instance and context, or null if no editor exists.
- [cellEditingRequested](https://grid.syidax.com/docs/events/cellEditingRequested.md) — Emitted when cell editing is requested. Distinguish later cancellation, commit, and value-change events.
- [cellEditingCancelled](https://grid.syidax.com/docs/events/cellEditingCancelled.md) — Emitted when cell editing is cancelled. Do not treat it as a successful server save.
- [cellEditingCommitted](https://grid.syidax.com/docs/events/cellEditingCommitted.md) — Emitted when cell editing is committed. Also inspect cellValueChanged for actual value changes.
- [rowValueChanged](https://grid.syidax.com/docs/events/rowValueChanged.md) — Reports full-row value changes. Use when defining a save unit for an entire row.
- [rowEditStart](https://grid.syidax.com/docs/events/rowEditStart.md) — Emitted when full-row editing starts.
- [rowEditStop](https://grid.syidax.com/docs/events/rowEditStop.md) — Emitted when full-row editing ends. Distinguish commit from cancellation.

<a id="next"></a>

## Related reading

- [How rows, columns, and IDs relate](https://grid.syidax.com/docs/guides/concepts.md)
- [Connect results and events](https://grid.syidax.com/docs/guides/data-event-access.md)
- [Explore in Features](https://grid.syidax.com/grid/cell-editing) — The guide describes which interactions are available to try.