# Data and events

Grid APIs read or change the current state; events report the results of user interactions or data changes. Combine them to build save buttons, detail panels, and change histories.

Canonical: https://grid.syidax.com/docs/guides/data-event-access/

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

## How it works and when to use it

Most public methods return Promises, so use await to read completion results. Event names are case-sensitive, and payloads are carried in CustomEvent.detail.

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. Read editing results

Check the actual event type for the edited cell and its before/after values.

```javascript
const controller = new AbortController();
grid.addEventListener('cellValueChanged', event => {
  console.log(event.detail);
}, { signal: controller.signal });
```

Verify the result: Build the app's save payload from actual changes rather than counting events.

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

## Example 2. Check call results

Read selected rows through the API instead of assuming they are the first items in the source array.

```javascript
const selectedIds = await grid.getSelectedRowIds();
console.log(selectedIds);
```

Verify the result: Use selected IDs to determine approval or export targets. Calling a method and completing a server save are separate steps.

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

## Example 3. Clean up on view disposal

Use the first example's AbortController to remove subscriptions together.

```javascript
controller.abort();
```

Verify the result: Events will not run twice when the view reopens. Also clean up app-created WebSockets, timers, and requests.

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

## Combining features and troubleshooting

Writing the same value after receiving an event can create an event loop. Distinguish user changes from app-applied updates.

Do not confuse an event's rowIndex with a stable rowId. Use IDs for persistent keys.

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

## APIs used by this feature

- [context](https://grid.syidax.com/docs/options/context.md) — Passes shared app context to callbacks and the Grid API, such as app-managed permissions and services.
- [getApi](https://grid.syidax.com/docs/methods/getApi.md) — Accesses the current Grid's typed API and app context. Read from a fully initialized element.
- [getRow](https://grid.syidax.com/docs/methods/getRow.md) — Finds a row object by stable row ID, rather than display index.
- [getDisplayedRowAtIndex](https://grid.syidax.com/docs/methods/getDisplayedRowAtIndex.md) — Finds a row object by its current display index. Sorting, filtering, and grouping can change the row at an index.
- [forEachRow](https://grid.syidax.com/docs/methods/forEachRow.md) — Runs a callback for each row object. Use forEachDisplayedRow when display order matters.
- [forEachDisplayedRow](https://grid.syidax.com/docs/methods/forEachDisplayedRow.md) — Iterates current displayed rows for app features that distinguish source order from display order.
- [cellClicked](https://grid.syidax.com/docs/events/cellClicked.md) — Emitted on a cell click. Read the row, field, and input context from detail.
- [cellDoubleClicked](https://grid.syidax.com/docs/events/cellDoubleClicked.md) — Emitted on a cell double-click. Avoid conflicts between starting editing and opening app details.
- [rowClicked](https://grid.syidax.com/docs/events/rowClicked.md) — Emitted on a row click. Distinguish the click itself from the resulting selection.
- [gridObjectChanged](https://grid.syidax.com/docs/events/gridObjectChanged.md) — Emitted when public objects such as rows and columns change. Read the target and changes from detail.

<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/data-event-access) — The guide describes which interactions are available to try.