ReactGrid Tutorial: How to Build an Interactive React Spreadsheet Component from Scratch

Published: January 15, 2025 ·
Updated: July 10, 2025 ·
12 min read · Covers ReactGrid v7+

If you've ever tried to put a spreadsheet-like UI inside a React application, you know the pain: most
React data grid libraries
give you a glorified HTML table with sorting, and call it a day. ReactGrid takes a
fundamentally different approach — it's built from the ground up to behave like a real spreadsheet, with
non-rectangular cell layouts, custom cell types, inline editing, and smooth keyboard navigation that
doesn't make your users reach for the mouse every five seconds. This guide walks you through everything:
installation, core concepts, cell editing, formula integration, and a working example you can drop into a
project today.

Why ReactGrid Instead of Yet Another React Table Library

The React ecosystem is not short on table and grid solutions. You've got
TanStack Table,
AG Grid, MUI DataGrid, and a dozen more. So why does
ReactGrid deserve a
separate mental slot? Because its design goal is different. Most grids optimize for displaying and sorting
large datasets. ReactGrid optimizes for editing them — the way a spreadsheet does. Cells can
span rows and columns freely, the user can tab through them in a natural reading order, copy-paste works
exactly like Excel, and you can define completely custom cell renderers without fighting the library's
internals.

The practical consequence is that ReactGrid fits a different class of problems. Budget
planners, financial models, data entry forms, scheduling tables, pricing matrices — any UI where the user
needs to navigate and edit a two-dimensional structure fluidly. If you just need a read-only table with
filtering and pagination, TanStack Table is probably the right call. But the moment users start
complaining that your interface "feels nothing like Excel," ReactGrid is worth a serious look.

There's also the licensing angle worth acknowledging upfront. ReactGrid ships a Community edition under
MIT — genuinely free, no usage restrictions, no watermarks, no annual audits. A Pro tier unlocks sticky
rows/columns, range selection, row/column resizing, and a handful of performance improvements for very
large grids. For most internal tools and mid-sized applications, the Community build covers all the
bases.

ReactGrid Installation and Project Setup

Getting ReactGrid installed
is a single command. The package lives on npm and has no peer dependencies beyond React itself, which
means it slots into any existing Create React App, Vite, or Next.js project without ceremony.

# npm
npm install @silevis/reactgrid

# yarn
yarn add @silevis/reactgrid

# pnpm
pnpm add @silevis/reactgrid

After installation, import the default stylesheet — this gives you the baseline grid appearance, focus
rings, and selection highlights. Without it the grid renders as an unstyled mess that will confuse your
users and embarrass you at code review.

// In your root file or the component that uses ReactGrid
import "@silevis/reactgrid/styles.css";

ReactGrid works with both JavaScript and TypeScript. The package ships full TypeScript definitions, and if
you're starting a new project in 2025 there's no reason not to use them — the type hints for
CellChange, Column, Row, and CellTemplate will save
you a lot of head-scratching later. All examples in this tutorial are written in TypeScript, but the
JavaScript equivalents are identical minus the type annotations.

Core Concepts: Rows, Columns, and Cells

Before writing any JSX, it's worth understanding how ReactGrid models data, because it's meaningfully
different from a typical table component. The grid is defined by three independent structures:
columns, rows, and the cells within those rows. Columns
define width and identity. Rows define height and carry an array of cell objects. Cells carry type
information, values, and per-cell configuration. None of these structures hold references to each other —
the grid reconciles them by position at render time.

This separation is what makes non-rectangular layouts possible. A cell can declare a
colspan or rowspan and ReactGrid handles the geometry automatically. You don't
have to manually patch surrounding cells with type: "empty" placeholders the way you do with
raw HTML tables — the library figures out that certain positions are occupied and routes keyboard
navigation around them intelligently.

The cell type system is the most powerful concept in the library. Built-in types include
text, number, date, time, email,
url, checkbox, and dropdown. Each type has a corresponding
renderer and editor. When the user activates a cell, ReactGrid automatically swaps the renderer for the
appropriate editor — an <input type="number"> for number cells, a
<select> for dropdowns, and so on. You can also define custom cell types that render
arbitrary React components, which is where things get genuinely interesting.

Your First ReactGrid Example: A Simple Editable Spreadsheet

Let's build something concrete. The following example creates a small budget table with a header row,
editable number cells, and a read-only total row. It's the kind of thing that takes thirty minutes with
a DIY approach and about fifteen minutes with ReactGrid — once you understand the data model.

import React, { useState } from "react";
import { ReactGrid, Column, Row, CellChange, NumberCell, TextCell } from "@silevis/reactgrid";
import "@silevis/reactgrid/styles.css";

interface BudgetRow {
  category: string;
  q1: number;
  q2: number;
  q3: number;
  q4: number;
}

const getColumns = (): Column[] => [
  { columnId: "category", width: 160 },
  { columnId: "q1",       width: 100 },
  { columnId: "q2",       width: 100 },
  { columnId: "q3",       width: 100 },
  { columnId: "q4",       width: 100 },
];

const getHeaderRow = (): Row => ({
  rowId: "header",
  cells: [
    { type: "header", text: "Category" },
    { type: "header", text: "Q1" },
    { type: "header", text: "Q2" },
    { type: "header", text: "Q3" },
    { type: "header", text: "Q4" },
  ],
});

const getDataRows = (data: BudgetRow[]): Row[] =>
  data.map((row, idx) => ({
    rowId: idx,
    cells: [
      { type: "text",   text:  row.category, nonEditable: true },
      { type: "number", value: row.q1 },
      { type: "number", value: row.q2 },
      { type: "number", value: row.q3 },
      { type: "number", value: row.q4 },
    ],
  }));

const getTotalRow = (data: BudgetRow[]): Row => {
  const sum = (key: keyof Omit<BudgetRow, "category">) =>
    data.reduce((acc, r) => acc + r[key], 0);
  return {
    rowId: "total",
    cells: [
      { type: "header", text: "Total" },
      { type: "number", value: sum("q1"), nonEditable: true },
      { type: "number", value: sum("q2"), nonEditable: true },
      { type: "number", value: sum("q3"), nonEditable: true },
      { type: "number", value: sum("q4"), nonEditable: true },
    ],
  };
};

const initialData: BudgetRow[] = [
  { category: "Marketing",   q1: 12000, q2: 14500, q3: 13200, q4: 16800 },
  { category: "Engineering", q1: 45000, q2: 47000, q3: 46000, q4: 50000 },
  { category: "Operations",  q1:  8500, q2:  9000, q3:  8700, q4:  9500 },
];

export const BudgetGrid: React.FC = () => {
  const [data, setData] = useState<BudgetRow[]>(initialData);

  const columns = getColumns();
  const rows    = [getHeaderRow(), ...getDataRows(data), getTotalRow(data)];

  const handleChanges = (changes: CellChange[]) => {
    setData(prev => {
      const next = [...prev];
      changes.forEach(change => {
        const rowIdx = change.rowId as number;
        const colId  = change.columnId as keyof BudgetRow;
        if (change.type === "number") {
          (next[rowIdx] as any)[colId] = (change.newCell as NumberCell).value;
        }
      });
      return next;
    });
  };

  return (
    <ReactGrid
      rows={rows}
      columns={columns}
      onCellsChanged={handleChanges}
      enableFillHandle
      enableRangeSelection
    />
  );
};

A few things worth noting in this example. First, the total row recalculates automatically on every
render because getTotalRow derives its values directly from state — no manual event wiring
required. Second, enableFillHandle gives users the Excel-style drag handle to fill a series
of cells, which users absolutely will expect and will absolutely complain about if it's missing.
Third, marking the category cells nonEditable: true takes one property — ReactGrid handles
the visual distinction and blocks keyboard editing automatically.

The onCellsChanged callback receives a flat array of all changes in a single batch. This is
deliberate — when a user drags the fill handle across twelve cells, you get one callback with twelve
changes rather than twelve separate renders. It's a better model for performance and also makes undo/redo
implementation far more straightforward.

ReactGrid Cell Editing: Custom Cell Types in Practice

The built-in cell types cover a lot of ground, but the moment you need something bespoke — a star-rating
cell, a currency picker, a cell that shows a sparkline — you'll reach for the custom cell template API.
Creating a custom cell type involves two pieces: a type definition that extends Cell, and a
class (or object) implementing CellTemplate<YourCellType>. The template defines how
to render the cell in view mode, how to render it in edit mode, and how to parse keyboard input.

import { CellTemplate, Cell, Compatible, Uncertain, getCellProperty } from "@silevis/reactgrid";

// 1. Define the cell type
export interface RatingCell extends Cell {
  type:   "rating";
  rating: number; // 0–5
}

// 2. Implement the template
export class RatingCellTemplate implements CellTemplate<RatingCell> {

  getCompatibleCell(uncertainCell: Uncertain<RatingCell>): Compatible<RatingCell> {
    const rating = getCellProperty(uncertainCell, "rating", "number");
    return { ...uncertainCell, rating, text: String(rating), value: rating };
  }

  render(cell: Compatible<RatingCell>, isInEditMode: boolean, onCellChanged: (cell: Compatible<RatingCell>, commit: boolean) => void) {
    return (
      <div style={{ display: "flex", gap: 4, justifyContent: "center" }}>
        {[1, 2, 3, 4, 5].map(star => (
          <span
            key={star}
            style={{ cursor: "pointer", color: star <= cell.rating ? "#f59e0b" : "#d1d5db", fontSize: 18 }}
            onPointerDown={e => {
              e.stopPropagation();
              onCellChanged({ ...cell, rating: star }, true);
            }}
          >★</span>
        ))}
      </div>
    );
  }

  isFocusable = () => true;
  getClassName = () => "rating-cell";
}

To register the template, pass it via the customCellTemplates prop on the
<ReactGrid> component:
<ReactGrid customCellTemplates={{ rating: new RatingCellTemplate() }} ... />.
After that, any cell with type: "rating" in your row data will use this renderer. The
integration is clean enough that custom cells participate in copy-paste, keyboard navigation, and
onCellsChanged just like built-in types.

One thing the ReactGrid documentation doesn't emphasize enough: keep your custom template's
render function as lean as possible. ReactGrid can call it frequently during selection and
scroll events. If your renderer spins up heavy computations or causes layout thrash, you'll feel it
during keyboard navigation. Memoize derived values inside the template or shift them into the cell data
itself.

Adding Formula Support with HyperFormula

ReactGrid doesn't ship a built-in formula engine — and that's a reasonable architectural decision. Formula
evaluation is a complex, standalone problem, and bundling a mediocre one into the grid library would do
nobody any favors. Instead, ReactGrid integrates cleanly with
HyperFormula,
an MIT-licensed formula engine that supports over 400 Excel-compatible functions. The integration isn't
magical — you wire it up yourself — but it's less work than it sounds.

import HyperFormula from "hyperformula";

// Initialize HyperFormula with your sheet data
const hf = HyperFormula.buildFromArray(
  [
    ["Marketing",   12000, 14500, 13200, 16800, "=SUM(B1:E1)"],
    ["Engineering", 45000, 47000, 46000, 50000, "=SUM(B2:E2)"],
    ["Operations",   8500,  9000,  8700,  9500, "=SUM(B3:E3)"],
  ],
  { licenseKey: "gpl-v3" } // HyperFormula is GPL-v3 for open-source use
);

// Read evaluated values for rendering
const getCellValue = (row: number, col: number) =>
  hf.getCellValue({ sheet: 0, row, col });

// On cell change, update HyperFormula and re-derive grid rows
const handleChanges = (changes: CellChange[]) => {
  changes.forEach(change => {
    if (change.type === "number") {
      hf.setCellContents(
        { sheet: 0, row: change.rowId as number, col: columnIdToIndex(change.columnId) },
        (change.newCell as NumberCell).value
      );
    }
  });
  // Trigger re-render by updating state
  setVersion(v => v + 1);
};

The key insight is that HyperFormula owns the data model and evaluates formulas; ReactGrid owns the
rendering and editing UX. Your component state becomes a version counter or a shallow copy of evaluated
values that triggers re-renders. It's a clean separation and performs well for grids up to a few thousand
cells. For larger datasets, HyperFormula's batch update APIs and lazy evaluation options become relevant
— their documentation covers this in detail.

One practical note on licensing: HyperFormula is available under GPL-v3 for open-source projects and
under a commercial license for proprietary software. If your React spreadsheet component is shipping
inside a closed-source product, factor in the HyperFormula license cost. The combination of ReactGrid Pro
plus HyperFormula commercial is still significantly cheaper than, say, embedding an AG Grid Enterprise
license, and you get a much better spreadsheet-like editing experience in the bargain.

Handling Large Datasets and Performance in React Data Grid Scenarios

ReactGrid renders the entire grid into the DOM by default — there's no built-in virtualization in the
Community edition. For most internal tools, this is fine; a 50×20 grid is around 1,000 DOM nodes, which
modern browsers handle without complaint. Problems start appearing around 200+ rows or when you're
running heavy custom cell renderers on every cell simultaneously. At that point, you have a few options
depending on your setup.

The first and simplest option is pagination. Slice your dataset into pages of 50–100 rows, render only
the current page, and provide navigation controls. Users doing data entry rarely need to see more than a
screenful at once, and pagination is conceptually familiar. The implementation is trivial — just filter
your rows array before passing it to <ReactGrid>.

For genuinely large datasets where scrolling through rows is a core requirement, the ReactGrid Pro tier
offers row and column virtualization. If Pro isn't an option, you can implement a crude version manually
by tracking the scroll position of the container element and slicing the rows array accordingly — though
you'll need to account for variable row heights and maintain a stable rowId mapping to
prevent ReactGrid from losing focus state during scroll. It's doable but not fun, which is an honest
argument for the Pro license when the use case demands it.

ReactGrid in a Real-World React Data Manipulation Workflow

A common pattern in internal tools is the "load → edit → save" cycle: fetch data from an API, let the
user modify it in a spreadsheet-like interface, then POST the changes back. ReactGrid fits this workflow
naturally, but there are a couple of implementation decisions worth making intentionally rather than
stumbling into them.

First, decide whether you want optimistic or explicit saves. Optimistic updates (writing
to local state immediately on onCellsChanged, syncing to the API in the background) feel
snappier but require rollback logic on failure. Explicit saves (collecting changes in a dirty-state map
and sending them on a "Save" button click) are simpler to reason about and easier to test. The
onCellsChanged callback gives you all the information you need for both approaches — the
choice is purely about the UX contract you want to make with your users.

Second, keep your cell data transformations outside the component tree. Define getRows and
getColumns as pure functions that take your domain data and return ReactGrid-compatible
structures. This makes them trivial to unit test, easy to memoize with useMemo, and simple
to modify as requirements evolve — which they always do. The
getting started guide on dev.to
follows this pattern throughout and it shows in how readable the final component is.

Third, embrace ReactGrid's highlights prop for validation feedback. Pass an array of
CellLocation objects with a className to visually flag cells with invalid data
— cells where a number is out of range, a required field is empty, or a formula returned an error. It's
a one-liner per validation rule and it provides the kind of immediate, spatial feedback that a toast
notification simply cannot match on a dense data grid.

Semantic Core Reference