LyteNyte Grid logo for light mode. Links back to the documentation home page.
Grid

Grid Events

This guide explains how to listen for and handle grid events. LyteNyte Grid fires events in response to specific user interactions or when imperative API methods run.

Handling Events

LyteNyte Grid defines its own events that fire on specific user interactions. This guide does not cover every event that can cause the grid to fire. For more information, refer to the Events API reference for details on individual events.

Listening to Events

The simplest way to listen to events is to add an event listener to the Grid.Root component. The demo below alerts the user every time a row is selected; click any row to trigger the event.

Row Selection Events

The code shown below for handling the event is straightforward and should feel familiar to React developers.

<Grid.Root
grid={grid}
onRowSelectEnd={(p) => {
alert(`The row with ID ${p.selected} was ${p.deselect ? "deselected" : "selected"}`);
}}
></Grid.Root>

Cancelling Events

The row selection event that's been used in this guide so far is named onRowSelectEnd. Many LyteNyte Grid events are split into two or more phases because some actions may be asynchronous. For row selection, LyteNyte Grid also fires an onRowSelectBegin event when the user attempts to select a row.

The event object passed to onRowSelectBegin includes a preventDefault method. Call this method to cancel the selection. If you call preventDefault, LyteNyte Grid does not change the selection state and does not fire the onRowSelectEnd event.

<Grid.Root
grid={grid}
onRowSelectBegin={(p) => {
// If my condition is met, then prevent the row selection from happening
if (myCondition) {
p.preventDefault();
return;
}
}}
onRowSelectEnd={(p) => {
alert(`The row with ID ${p.selected} was ${p.deselect ? "deselected" : "selected"}`);
}}
></Grid.Root>

Imperatively Adding Event Listeners

LyteNyte Grid's headless architecture allows you to create grid state higher in the React component tree, separate from where you render Grid.Root. Instead of prop-drilling event handlers down to Grid.Root, you can add listeners imperatively through the grid API.

Imperative listeners must be cleaned up, but they provide a convenient way to subscribe to events when the component that creates state is different from the component that renders the grid.

The example below demonstrates adding an event listener imperatively. By clicking any row, you trigger the event, which displays a notification and highlights the selected row.

Imperative Event Listeners

This example behaves the same as the previous one, it alerts the user whenever a row is selected, but it attaches the listener inside a useEffect:

useEffect(() => {
return grid.api.eventAddListener("rowSelectEnd", (p) => {
alert(`The row with ID ${p.selected} was ${p.deselect ? "deselected" : "selected"}`);
});
}, [grid.api]);

This pattern returns the cleanup function from eventAddListener as the effect's cleanup. That function removes the event listener when the effect is disposed. In general, use this pattern whenever you add grid event listeners imperatively.

LyteNyte Grid Events Vs DOM Events

LyteNyte Grid events are not DOM events and behave differently. They do not bubble, and the event object shape is specific to each grid event. You can only attach listeners through the grid API's eventAddListener method or via event props on Grid.Root.

For most use cases, you can ignore these differences and treat grid events as a separate, grid-specific event system. This note exists to prevent confusion with DOM event behavior.

Grid Component Event Listeners

If you review the list of events in the API Reference, you will notice that all of them are tied to grid-specific interactions. LyteNyte Grid does not define events such as cell-clicked events or scroll events.This design follows the headless component architecture.

Grid components accept normal DOM event listeners, which you can use for common interactions. You do not need to learn a custom system for these cases. For example, you can add a scroll listener to the Grid.Viewport component to track the current scroll position:

Scroll Event Listeners

Scroll Position: (0, 0)

The scroll listener uses the same pattern as any other React DOM event.

<Grid.Viewport
onScroll={(ev) => {
setScrollX(ev.currentTarget.scrollLeft);
setScrollY(ev.currentTarget.scrollTop);
}}
/>

Your existing React event handling experience translates directly to LyteNyte Grid components.

Next Step