Documentation home page
LyteNyte Grid logo for dark mode
GuidesAPI ReferenceChangelog
Grid

Grid Reactivity

LyteNyte Grid is built on declarative principles. Its state system is fully reactive, automatically keeping the view synchronized with state changes. This follows React's core philosophy that "view is a function of state."

This reactivity can be leveraged naturally in your React code, integrating smoothly with other components. LyteNyte Grid achieves this by using standard React primitives, enabling seamless interaction throughout your application.

The Grid State Object

The grid state object serves as your interface to LyteNyte Grid. It's returned by the useLyteNytePro (or useLyteNyteCore) hook and contains a state property. Examining this object's types reveals that most keys match those in the initial state object passed to useLyteNytePro - this is intentional. LyteNyte Grid also adds several helpful fields.

While the keys match, the values differ significantly. Values in the state object are signals (observable values) specifically designed for LyteNyte Grid's needs.

Each signal provides methods including watch, peek, set, and use. To integrate a signal with React, call the use method - this React hook retrieves the current state value and triggers re-renders when that value changes. The set method updates a signal's value.

This becomes clearer with an example:

LyteNyte Signal Use
Currently selected rows: 3-center, 4-center

The power of the use call extends beyond basic reactivity. Since LyteNyte Grid's state lives in the object returned by useLyteNytePro, you can elevate this state to higher component levels and share it throughout your application.

For instance, you can build a table that presents a line chart based on the selected row. We do this by passing the grid state to a price chart component. In the price chart component we use grid.state.rowSelectionSelectedIds.use function to reactively subscribe to changes to the row selection:

Chart Line On Row Selection

This approach lets you maintain React's recommended one-way data flow without resorting to complex synchronization methods.

The Other Signal Methods

Beyond use, signal objects offer several other methods for specific scenarios.

The peek Method

The peek method retrieves a signal's current value without following hook rules, making it callable from anywhere in your code.

You may notice a get method on signal objects. While functionally identical to peek, get is used internally by LyteNyte Grid's state library for signal connections. Though safe to use, prefer peek in your own code.

The set Method

The set method changes a signal's value. Similar to React's setState, it accepts either a new value or a function that receives the current value and returns an updated one:

const grid = useLyteNytePro({});
 
grid.state.rowHeight.set(22);
// Or
grid.state.rowHeight.set((prev) => prev + 10); // current height + 10

Important: Like React's useState setter, there's no guarantee a newly set value is immediately available after calling set. Avoid code that immediately accesses a newly set value:

grid.state.rowHeight.set(24);
 
// INCORRECT - may return 24 or the previous value
const row = grid.state.rowHeight.peek();

Instead, capture the current value first, then set the new value:

const currentRowHeight = grid.state.rowHeight.peek();
 
grid.state.rowHeight.set(24);

The watch Method

The watch method monitors changes to a signal's value. It shouldn't be used in React's render path (place it inside useEffect or event handlers instead). Think of watch as creating an event listener for value changes, requiring proper cleanup when used.

For example, to log each row height change:

const grid = useLyteNytePro({});
 
const rowHeightSignal = grid.state.rowHeight;
 
useEffect(() => {
  const remove = rowHeightSignal.watch(() => {
    console.log(rowHeightSignal.peek());
  });
 
  return () => remove();
}, [rowHeightSignal]);

Note that we read the signal's value inside the watch callback. The callback doesn't receive the changes; it simply notifies when changes occur. This happens because LyteNyte Grid evaluates state changes lazily - multiple consecutive changes to the same signal trigger only a single watch call:

rowHeightSignal.set(24);
rowHeightSignal.set(32);
rowHeightSignal.set(18);

The code above results in just one watch call. Additionally, watch callbacks execute on the microtask queue.