---
title: "API Events Usage | Docs"
description: "ZingGrid comes with its own set of events. Many of these events help signal when the grid or its components are rendered, or when an interaction occurs."
url: https://www.zinggrid.com/docs/api/events/usage
---

```text
experiment_id: web-retrieval-v1
fixture_id: /docs/api/events/usage.md
mode: provenance
representation: markdown
origin_response_id: 0a17dcc99bb3509be701c59aeb15c33b
version: 2026-10-21
version_created_at_utc: 2026-10-21T20:42:35.598Z
version_nonce: 202960d732b70dade2e3bc6308275a5c
generated_at_utc: 2026-11-06T20:29:40.935Z
response_nonce: 6c23cc98bbfbd4767ac137d937689a11
```

# API Events Usage

ZingGrid comes with its own set of events that work similarly to modern event handlers. Many of these events help signal when the grid or its components are rendered, or when an interaction occurs.

## Events Usage

ZingGrid events have to be added after ZingGrid is available in the DOM. You can do this by assigning a reference to your grid, like so:

```javascript
  // Grab reference to grid
  const zgRef = document.querySelector('zing-grid');
```

These events are added like native events and the best practice is to use `addEventListener`. In the example below, we attach the `record:click` event to demonstrate how to properly add an event in ZingGrid.

```javascript
const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('record:click', (e) => {
  // destruct e.detail object for ZingGrid information
  const { ZGData, ZGEvent, ZGTarget } = e.detail;
  console.log('--- Event Details ---\n', ZGData, ZGEvent, ZGTarget);
});
```

**All event** details can be accessed through `e.detail`. Most events will return the following object structure:

```javascript
e.detail: {
  // Information from ZingGrid internal components.
  ZGData: {...},
  // Points to any relevant built in event.
  ZGEvent: {...},
  // Points the DOM element the event actually happened on.
  ZGTarget: {...},
}
```

e.detail Objects

| ZGData | ZGEvent | ZGTarget |
| --- | --- | --- |
| Information from ZingGrid internal components, including cell, row, grid, and other components. | Points to any relevant built-in event (i.e., the actual click event in the case of `cell:click`). | A reference to the DOM object relative to that action (e.g., cell, row, grid). |

If you need to wait until everything in the grid is ready (typically when running set methods on the grid), you will use `zgRef.executeOnLoad()` to determine synchronous actions on the grid.

> **Warning:** Note that ZingGrid events are not compatible with on-tag event attributes or direct bound events. Therefore, the following examples will not work:
>
> Adding an event handler as an attribute:
>
> ```javascript
> <zing-grid onclick="click"></zing-grid>
> <script>
>   function click() { alert('Click!'); }
> </script>
> ```
>
> Binding events directly (as opposed to using a modern event listener):
>
> ```javascript
> document.querySelector('zing-grid').onrender = function click() {
>   alert('Rendered');
> };
> ```