lytenyte-grid

LyteNyte Grid is a headless React data grid with two editions:

• Core — @1771technologies/lytenyte-core (Apache 2.0, free, no license required)
• PRO — @1771technologies/lytenyte-pro (commercial, superset of Core)

PRO licensing: PRO can be installed and used freely for evaluation — no license key is needed to try it. A watermark ("used for evaluation") appears when no key is set. A license key is required to remove the watermark for production deployments. License validation is offline; no network request is made. If the user is building/prototyping and hasn't set up a license yet, that is fine — they can add it before shipping.

Quick Start

// or @1771technologies/lytenyte-core if already installed
import { Grid, useClientDataSource } from "@1771technologies/lytenyte-pro";
import "@1771technologies/lytenyte-pro/grid-full.css";

interface GridSpec {
  readonly data: { name: string; price: number };
}

function MyGrid() {
  const ds = useClientDataSource({ data: myData });
  const [columns, setColumns] = useState<Grid.Column<GridSpec>[]>([
    { id: "name", name: "Name" },
    { id: "price", name: "Price", type: "number" },
  ]);

  return (
    <div className="ln-light ln-grid" style={{ height: 500 }}>
      <Grid<GridSpec> rowSource={ds} columns={columns} onColumnsChange={setColumns} rowHeight={40} />
    </div>
  );
}

Gotchas

• useState and other locally created state are cleared when the user scrolls and rows are removed by virtualization: Lift state into a React context or provide an apiExtension.
• Memoize all non-primitive props: columns, columnBase, events, apiExtension, etc. must be stable references (use useMemo/useCallback) or use the React Compiler. Inline objects cause full grid re-renders.
• Pivoting requires ds.usePivotProps() — calling useClientDataSource with pivotMode: true is not enough. You must also spread ds.usePivotProps() onto <Grid /> or the grid will not render pivot columns.
• Server source: queryKey change = full reset — putting a sort/filter model in queryKey causes the grid to discard all loaded data and restart from row 0. This is intentional; use it to trigger refetches.
• rtl prop required for RTL — the grid does NOT detect RTL from the CSS direction property. Set <Grid rtl /> explicitly.
• CSP requires style-src 'unsafe-inline' — LyteNyte Grid uses inline styles for layout/virtualization. Most modern frameworks (Vite, Next.js) already include this.
• Column id is immutable — never change a column's id after creation. It is used as a stable key throughout the grid.
• usePiece for reactive extension state — to expose reactive state through apiExtension (e.g., a filter model), wrap it in usePiece(value, setter). Plain values in the extension object are not reactive.
• Context menu: suppress browser default — always call event.preventDefault() and event.stopPropagation() in contextmenu handlers, or the browser menu appears over yours.
• Popover editors: disable editOnPrintable — if your edit renderer uses character keys (e.g., a SmartSelect), set editOnPrintable: false on the column to prevent the grid from entering edit mode on every keypress.
• The grid container must have a defined size — the <Grid /> component fills its parent 100%. If the parent has no explicit height, the grid renders with zero height and appears blank. Always set a fixed pixel height, or use a flex/grid layout with flex: 1.
• CSS import is optional but required for the prebuilt themes — LyteNyte Grid is headless by design. If you don't import the CSS, the grid renders functionally but with no built-in styles; you must supply your own via headless mode, Tailwind, CSS Modules, or Emotion. Only import the CSS if you want a prebuilt theme or the default styling.
• columns always needs onColumnsChange — omitting it means column resizes, reorders, and sort-state changes made by the user are silently discarded. The grid needs to call setColumns to persist any column mutation.

Key Patterns

• GridSpec — define once per grid: interface GridSpec { readonly data: MyType }. Drives all types.
• All filters are custom predicates — (row: RowLeaf<T>) => boolean. No built-in filter UI.
• apiExtension — adds custom methods/state to the grid API. Use function form (api) => ({...}) when the extension needs to call grid API methods.

Load References On Demand

Read a reference file only when the task requires it. Do not load all files upfront.