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.Rootgrid={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.Rootgrid={grid}onRowSelectBegin={(p) => {// If my condition is met, then prevent the row selection from happeningif (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
The scroll listener uses the same pattern as any other React DOM event.
<Grid.ViewportonScroll={(ev) => {setScrollX(ev.currentTarget.scrollLeft);setScrollY(ev.currentTarget.scrollTop);}}/>
Your existing React event handling experience translates directly to LyteNyte Grid components.
Next Step
- Headless Component Parts: Learn about the component parts that make up LyteNyte Grid.
- Row and Column Virtualization: Learn how LyteNyte Grid enables performance at scale with row and column virtualization.
- Grid Atoms & Reactivity: Learn how to manage reactivity and state changes in LyteNyte Grid.
Headless Component Parts
LyteNyte Grid is a headless data grid. Each part of the grid is split into constituent components that you can compose declaratively to form the grid view.
Row & Column Virtualization
LyteNyte Grid virtualizes rows and columns. This guide explains virtualization, highlights its performance benefits, and outlines key considerations for developers.