Docs

API Events

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.

executeOnLoad()

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

Example Usage

const zgRef = document.querySelector('zing-grid');
zgRef.executeOnLoad(() => {
  // apply ZingGrid methods in here like data:
  zgRef.setData();
});

Grid Events

zing-grid refers to the (<zing-grid>) element, and its associated events target the entire grid as a whole.

Note: Each inner-grid component also has their own events. You can test these events in the Events Playground.

Example Usage

const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('grid:ready', function(e) {
  console.log('--- (grid:ready) event fired ---', e);
});

Description

Fires the event once before the grid renders.

Important Return Values

Null

Demo

Description

Fires the event when the contextmenu is closed.

Important Return Values

Null

Demo

Description

Fires the event when the contextmenu is opened.

Important Return Values

Null

Demo

Description

Fires the event when selection is deselected in the grid.

Important Return Values

Null

Demo

Description

Fires the event when the pre-rendered grid is finished being hydrated.

Important Return Values

Null

Demo

Description

Fires the event when the (Esc) key is pressed.

Important Return Values

Null

Demo

Description

Fires the event when a page changes in the grid.

Important Return Values

  • Type: Number
    Name: ZGData.currentPage
    Description: The current page index.
  • Type: Number
    Name: ZGData.pageSize
    Description: The current `page-size` of the grid.

Demo

Description

Fires the event when the grid changes to the first page.

Important Return Values

  • Type: Number
    Name: ZGData.currentPage
    Description: The current page index.
  • Type: Number
    Name: ZGData.pageSize
    Description: The current `page-size` of the grid.

Demo

Description

Fires the event when the grid changes to the last page.

Important Return Values

  • Type: Number
    Name: ZGData.currentPage
    Description: The current page index.
  • Type: Number
    Name: ZGData.pageSize
    Description: The current `page-size` of the grid.

Demo

Description

Fires the event when the grid changes to the next page.

Important Return Values

  • Type: Number
    Name: ZGData.currentPage
    Description: The current page index.
  • Type: Number
    Name: ZGData.pageSize
    Description: The current `page-size` of the grid.

Demo

Description

Fires the event when the grid changes to the previous page.

Important Return Values

  • Type: Number
    Name: ZGData.currentPage
    Description: The current page index.
  • Type: Number
    Name: ZGData.pageSize
    Description: The current `page-size` of the grid.

Demo

Description

Fires the event when the page-size (amount of rows displaying) changes on the grid.

Important Return Values

  • Type: Number
    Name: ZGData.currentPage
    Description: The current page index.
  • Type: Number
    Name: ZGData.oldPageSize
    Description: The old `page-size` of the grid.
  • Type: Number
    Name: ZGData.pageSize
    Description: The current `page-size` of the grid.

Demo

Description

Fires the grid ready event when grid is ready.

Important Return Values

Null

Demo

Description

Fires the event when the grid is refreshed through grid controls or API method refresh().

Important Return Values

Null

Demo

Description

Fires the event once when grid renders.

Important Return Values

Null

Demo

Description

Fires the event when scrolling occurs in grid.

Important Return Values

  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

Description

Fires the event when selection is made in the grid.

Important Return Values

  • Type: Number
    Name: ZGData.columnEnd
    Description: The column where the selection ends.
  • Type: Number
    Name: ZGData.columnStart
    Description: The column where the selection starts.
  • Type: String | Array
    Name: ZGData.selectedData
    Description: A string for a single cell and array for multiple cells being selected.
  • Type: String
    Name: ZGData.rowEnd
    Description: The row where the selection ends.
  • Type: String
    Name: ZGData.rowStart
    Description: The row where the selection starts.

Demo

Description

Fires the event when selecting every cell (ctrl+a) in the grid.

Important Return Values

Null

Demo

Card Events

zg-card events are events that target the grid as a whole (zg-card Events Playground).

Example Usage

const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('card:click', function(e) {
  console.log('--- (card:click) event fired ---', e);
});

Description

Fires the card:click and record:click event when a click occurs on a record (card).

Important Return Values

  • Type: Object
    Name: ZGData.cell
    Description: The cell event details.
  • Type: Object
    Name: ZGData.data
    Description: The full data object for the row.
  • Type: String
    Name: ZGData.recordIndex
    Description: The unique identifier for the row, this identifier never changes.
  • Type: Number
    Name: ZGData.rowIndex
    Description: The current row index.
  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

Description

Fires the event when mouse is moved out a record (card).

Important Return Values

  • Type: Object
    Name: ZGData.cell
    Description: The cell event details.
  • Type: Object
    Name: ZGData.data
    Description: The full data object for the row.
  • Type: String
    Name: ZGData.recordIndex
    Description: The unique identifier for the row, this identifier never changes.
  • Type: Number
    Name: ZGData.rowIndex
    Description: The current row index.
  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

Description

Fires the event when mouse is moved over a record (card).

Important Return Values

  • Type: Object
    Name: ZGData.cell
    Description: The cell event details.
  • Type: Object
    Name: ZGData.data
    Description: The full data object for the row.
  • Type: String
    Name: ZGData.recordIndex
    Description: The unique identifier for the row, this identifier never changes.
  • Type: Number
    Name: ZGData.rowIndex
    Description: The current row index.
  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

Cell Events

zg-cell events are events that are triggered by each individual cell of the grid (zg-cell Events Playground).

Example Usage

const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('cell:click', function(e) {
  console.log('--- (cell:click) event fired ---', e);
});

Description

Fires the event before a cell is rendered.

Important Return Values

  • Type: Number
    Name: ZGData.columnIndex
    Description: The numerical index of the column.
  • Type: Object
    Name: ZGData.data
    Description: The full data object for the cell.
  • Type: String
    Name: ZGData.fieldIndex
    Description: The column index e.g. "firstName".
  • Type: Number
    Name: ZGData.rowIndex
    Description: The numerical index of the row.

Demo

Description

Fires the event when a click occurs to a cell.

Important Return Values

  • Type: String
    Name: ZGData.fieldIndex
    Description: The column index e.g. "firstName".
  • Type: Number
    Name: ZGData.rowIndex
    Description: The current row index.
  • Type: String
    Name: ZGData.type
    Description: The column type (default is text).
  • Type: String
    Name: ZGData.value
    Description: The value of the cell.
  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

Description

Fires the event when the cell editor is closed.

Important Return Values

  • Type: Boolean
    Name: ZGData.canceled
    Description: If the user canceled instead of saving the cell edit.
  • Type: Number
    Name: ZGData.columnIndex
    Description: The numerical index of the column.
  • Type: Object
    Name: ZGData.data
    Description: The full data object for the cell.
  • Type: String
    Name: ZGData.fieldIndex
    Description: The column index e.g. "firstName".
  • Type: String
    Name: ZGData.newValue
    Description: The new value of the cell after editing.
  • Type: Number
    Name: ZGData.rowIndex
    Description: The numerical index of the row.

Demo

Description

Fires the event when copying (ctrl+c) occurs in a cell.

Important Return Values

  • Type: Object
    Name: ZGData.data
    Description: The data copied from the cell.

Demo

Description

Fires the event when mouse is moved out of a cell.

Important Return Values

  • Type: String
    Name: ZGData.fieldIndex
    Description: The column index e.g. "firstName".
  • Type: Number
    Name: ZGData.rowIndex
    Description: The current row index.
  • Type: String
    Name: ZGData.type
    Description: The column type (default is text).
  • Type: String
    Name: ZGData.value
    Description: The value of the cell.
  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

Description

Fires the event when mouse is moved over a cell.

Important Return Values

  • Type: String
    Name: ZGData.fieldIndex
    Description: The column index e.g. "firstName".
  • Type: Number
    Name: ZGData.rowIndex
    Description: The current row index.
  • Type: String
    Name: ZGData.type
    Description: The column type (default is text).
  • Type: String
    Name: ZGData.value
    Description: The value of the cell.
  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

Description

Fires the event when the cell editor is opened.

Important Return Values

  • Type: Number
    Name: ZGData.columnIndex
    Description: The numerical index of the column.
  • Type: Object
    Name: ZGData.data
    Description: The full data object for the cell.
  • Type: String
    Name: ZGData.fieldIndex
    Description: The column index e.g. "firstName".
  • Type: Number
    Name: ZGData.rowIndex
    Description: The numerical index of the row.

Demo

Description

Fires the event when pasting (ctrl+p) occurs in a cell.

Important Return Values

  • Type: Object
    Name: ZGData.data
    Description: The data you paste

Demo

Description

Fires the event when a cell is rendered.

Important Return Values

  • Type: Number
    Name: ZGData.columnIndex
    Description: The numerical index of the column.
  • Type: Object
    Name: ZGData.data
    Description: The full data object for the cell.
  • Type: String
    Name: ZGData.fieldIndex
    Description: The column index e.g. "firstName".
  • Type: String
    Name: ZGData.renderedData
    Description: The rendered cell contents as a string.
  • Type: Number
    Name: ZGData.rowIndex
    Description: The numerical index of the row.

Demo

Description

Fires the event when right click occurs on a cell.

Important Return Values

  • Type: String
    Name: ZGData.fieldIndex
    Description: The column index e.g. "firstName".
  • Type: Number
    Name: ZGData.rowIndex
    Description: The current row index.
  • Type: String
    Name: ZGData.type
    Description: The column type (default is text).
  • Type: String
    Name: ZGData.value
    Description: The value of the cell.
  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

Column Events

zg-column refers to the columns of the grid. Events triggered by columns are zg-column events (zg-column Events Playground).

Example Usage

const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('column:click', function(e) {
  console.log('--- (column:click) event fired ---', e);
});

Description

Fires event when click on a column.

Important Return Values

  • Type: String
    Name: ZGData.fieldIndex
    Description: The column index e.g. "firstName".
  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

Description

Fires event when mouseout on a column.

Important Return Values

  • Type: String
    Name: ZGData.fieldIndex
    Description: The column index e.g. "firstName".
  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

Description

Fires event when mouseover on a column.

Important Return Values

  • Type: String
    Name: ZGData.fieldIndex
    Description: The column index e.g. "firstName".
  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

Data Events

zg-data events relate to data and any changes made to a record (zg-data Events Playground).

Example Usage

const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('data:load', function(e) {
  console.log('--- (data:load) event fired ---', e);
});

Description

Fires the event before a single cell value is changed.

Important Return Values

  • Type: Object
    Name: data
    Description: The data object associated with that record.
  • Type: String
    Name: fieldIndex
    Description: The column index e.g. "firstName".
  • Type: String
    Name: newValue
    Description: The new value of the cell.
  • Type: String
    Name: oldValue
    Description: The old value of the cell.
  • Type: String
    Name: recordIndex
    Description: The unique identifier for the row, this identifier never changes.
  • Type: Number
    Name: rowIndex
    Description: The index of the row.

Demo

Description

Fires the event after a single cell value is changed.

Important Return Values

  • Type: Object
    Name: data
    Description: The data object associated with that record.
  • Type: String
    Name: fieldIndex
    Description: The column index e.g. "firstName".
  • Type: String
    Name: newValue
    Description: The new value of the cell.
  • Type: String
    Name: oldValue
    Description: The old value of the cell.
  • Type: String
    Name: recordIndex
    Description: The unique identifier for the row, this identifier never changes.
  • Type: Number
    Name: rowIndex
    Description: The index of the row.

Demo

Description

Fires the event every time a new dataset is loaded in the grid.

Important Return Values

Null

Demo

Description

Fires the event before a record (row) is changed.

Important Return Values

  • Type: Array
    Name: changedField
    Description: The column indices that were changed e.g. ["firstName","lastName"].
  • Type: Object
    Name: data
    Description: The data object associated with that record.
  • Type: Object
    Name: oldData
    Description: The old data object associated with that record.
  • Type: String
    Name: recordIndex
    Description: The unique identifier for the row, this identifier never changes.
  • Type: Number
    Name: rowIndex
    Description: The index of the row.

Demo

Description

Fires the event before a record (row) is deleted from the grid.

Important Return Values

  • Type: Object
    Name: data
    Description: The data object associated with that record.
  • Type: Number
    Name: rowIndex
    Description: The index of the row.

Demo

Description

Fires the event before a new record (row) is added to the grid.

Important Return Values

  • Type: Object
    Name: data
    Description: The data object associated with that record.
  • Type: Number
    Name: rowIndex
    Description: The index of the row.

Demo

Description

Fires the event after a record (row) is changed.

Important Return Values

  • Type: Array
    Name: changedField
    Description: The column indices that were changed e.g. ["firstName","lastName"].
  • Type: Object
    Name: data
    Description: The data object associated with that record.
  • Type: Object
    Name: oldData
    Description: The old data object associated with that record.
  • Type: String
    Name: recordIndex
    Description: The unique identifier for the row, this identifier never changes.
  • Type: Number
    Name: rowIndex
    Description: The index of the row.

Demo

Description

Fires the event after a new record (row) is added to the grid.

Important Return Values

  • Type: Object
    Name: data
    Description: The data object associated with that record.
  • Type: Number
    Name: rowIndex
    Description: The index of the row.

Demo

Description

Fires the event when a record (row) is deleted from the grid.

Important Return Values

  • Type: Object
    Name: data
    Description: The data object associated with that record.

Demo

Header Events

zg-header events are triggered by the header cell of a column (zg-header Events Playground).

Example Usage

const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('header:click', function(e) {
  console.log('--- (header:click) event fired ---', e);
});

Description

Fires event when click on a header cell.

Important Return Values

  • Type: String
    Name: ZGData.cellIndex
    Description: The current cell index.
  • Type: String
    Name: ZGData.fieldIndex
    Description: The column index e.g. "firstName".
  • Type: String
    Name: ZGData.text
    Description: The value of the cell.
  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

Record Events

A record refers to a row and card in the grid. Events triggered by row and card mode are grouped into record events.

Example Usage

const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('record:click', function(e) {
  console.log('--- (record:click) event fired ---', e);
});

Description

Fires the row:click and record:click event when a click occurs on a record (row).

Important Return Values

  • Type: Object
    Name: ZGData.cell
    Description: The cell click details.
  • Type: Object
    Name: ZGData.data
    Description: The full data object for the row.
  • Type: String
    Name: ZGData.layout
    Description: The current layout of the grid, card or row.
  • Type: String
    Name: ZGData.recordIndex
    Description: The unique identifier for the row, this identifier never changes.
  • Type: Number
    Name: ZGData.rowIndex
    Description: The current row index.
  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

Description

Fires when the mouse cursor leaves the record (row).

Important Return Values

  • Type: Object
    Name: ZGData.cell
    Description: The cell click details.
  • Type: String
    Name: ZGData.data
    Description: The full data object for the row.
  • Type: String
    Name: ZGData.layout
    Description: The current layout of the grid, card or row.
  • Type: String
    Name: ZGData.recordIndex
    Description: The unique identifier for the row, this identifier never changes.
  • Type: Number
    Name: ZGData.rowIndex
    Description: The current row index.
  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

Description

Fires when the mouse cursor enter the record (row).

Important Return Values

  • Type: Object
    Name: ZGData.cell
    Description: The cell click details.
  • Type: String
    Name: ZGData.data
    Description: The full data object for the row.
  • Type: String
    Name: ZGData.layout
    Description: The current layout of the grid, card or row.
  • Type: String
    Name: ZGData.recordIndex
    Description: The unique identifier for the row, this identifier never changes.
  • Type: Number
    Name: ZGData.rowIndex
    Description: The current row index.
  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

Row Events

zg-row refers to a row in the grid. Events triggered by rows are zg-row events (zg-row Events Playground).

Example Usage

const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('row:click', function(e) {
  console.log('--- (row:click) event fired ---', e);
});

Description

Fires the row:click and record:click event when a click occurs on a record (row).

Important Return Values

  • Type: Object
    Name: ZGData.cell
    Description: The cell event details.
  • Type: Object
    Name: ZGData.data
    Description: The full data object for the row.
  • Type: String
    Name: ZGData.recordIndex
    Description: The unique identifier for the row, this identifier never changes.
  • Type: Number
    Name: ZGData.rowIndex
    Description: The current row index.
  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

Description

Fires the event when mouse is moved out a record (row).

Important Return Values

  • Type: Object
    Name: ZGData.cell
    Description: The cell event details.
  • Type: Object
    Name: ZGData.data
    Description: The full data object for the row.
  • Type: String
    Name: ZGData.recordIndex
    Description: The unique identifier for the row, this identifier never changes.
  • Type: Number
    Name: ZGData.rowIndex
    Description: The current row index.
  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

Description

Fires the event when mouse is moved over a record (row).

Important Return Values

  • Type: Object
    Name: ZGData.cell
    Description: The cell event details.
  • Type: Object
    Name: ZGData.data
    Description: The full data object for the row.
  • Type: String
    Name: ZGData.recordIndex
    Description: The unique identifier for the row, this identifier never changes.
  • Type: Number
    Name: ZGData.rowIndex
    Description: The current row index.
  • Type: Object
    Name: ZGEvent
    Description: A reference to the custom ZingGrid internal event.
  • Type: Object
    Name: ZGTarget
    Description: A reference to the DOM element.

Demo

On This Page