free-grid-react

A lightweight, high-performance, and fully configurable React grid component built with CSS Grid and TypeScript.

Release: 0.3.8 — 2026-07-12

• Added: Configurable row numbering with the rowNumbers prop for displaying incrementing row labels, plus rowNumberHeader for customizing the left-side header text.
• Fixed: Inline editing now supports Tab navigation between editable cells; Tab moves to the next editable column (and wraps to the next row when needed).

Demo

• Demo app: https://tonytomk.github.io/free-grid-react-demo/
• Demo app codebase: https://github.com/tonytomk/free-grid-react-app

Features

• 🚀 Performant: Built with native CSS Grid for smooth rendering.
• 🛠️ Configurable Headers: Bold labels with vertical dividers and togglable visibility.
• 🔘 Selection: Built-in checkbox selection with "Select All" support.
• 📁 Child Views: Easily expand rows to show detailed child components.
• 📶 Sorting: Built-in support for ascending and descending sort on any column.
• 🔍 Filtering: Column-specific filtering with dynamic string/number operator dropdowns.
• 🧺 Column Management: Hide/Show individual columns via header menu.
• ✍️ Inline Editing: Tap editable cells to edit values directly in the grid.
• ⌨️ Tab Navigation During Edit: Press Tab to move to the next editable cell in the row, or the next row when at the end of a row.
• 🔢 Configurable Row Numbering: Optionally show an incrementing row-number column.
• ➕ Configurable Row Addition: Optionally add a new row by clicking the last row.
• ⚙️ Manage Columns: Search and toggle multiple columns visibility through a right-aligned popover.
• 📄 Pagination: Integrated right-aligned pagination footer.
• ⌨️ TypeScript: First-class support for types and interfaces.

Installation

npm install free-grid-react

Quick Start

import { Grid } from 'free-grid-react';
import 'free-grid-react/dist/free-grid.css';

const columns = [
  { key: 'name', header: 'Name', flex: 1 },
  { key: 'email', header: 'Email', flex: 1 },
];

const data = [
  { id: 1, name: 'John Doe', email: '[email protected]' },
  { id: 2, name: 'Jane Smith', email: '[email protected]' },
];

function App() {
  const [rows, setRows] = useState(data);

  const handleCellEdit = (row, columnKey, value) => {
    setRows((prev) =>
      prev.map((item) =>
        item.id === row.id ? { ...item, [columnKey]: value } : item
      )
    );
  };

  const handleAddRow = () => {
    setRows((prev) => [
      ...prev,
      { id: prev.length + 1, name: '', email: '' },
    ]);
  };

  return (
    <Grid
      data={rows}
      columns={columns}
      selectable={true}
      theme="dark"
      isEditable={true}
      rowNumbers={true}
      onCellEdit={handleCellEdit}
      allowAddRow={true}
      onAddRow={handleAddRow}
      pagination={{ total: rows.length, page: 1, pageSize: 10 }}
    />
  );
}

Props

Grid Props

| Prop | Type | Description | | --- | --- | --- | | data | any[] | Array of data objects to display. | | columns | Column[] | Configuration for columns. | | showHeader | boolean | Whether to show the grid header (default: true). | | rowNumbers | boolean | Show an incrementing row-number column on the left. Defaults to false. | | rowNumberHeader | ReactNode | Custom header label for the row-number column. Defaults to #. | | selectionMode | single \| multiple | Row selection behavior. Defaults to multiple. | | stripedRows | boolean | Optional alternating row colors. Defaults to false. | | stripedRowOddColor | string | Custom color for odd striped rows. | | stripedRowEvenColor | string | Custom color for even striped rows. | | theme | light \| dark \| blue | Built-in surface theme preset. Defaults to light. | | gridColor | string | Main grid surface color. Defaults to white when omitted. | | gridTextColor | string | Optional text color for custom grid surfaces. | | allowSorting | boolean | true | Enable/disable sorting for the entire grid | | allowReordering | boolean | true | Enable/disable column drag-and-drop reordering | | allowResizing | boolean | true | Enable/disable interactive column resizing | | allowFiltering | boolean | Enable/disable column filtering in the header menu | | onFilterChange | (filter: ActiveFilter \| null) => void | Callback when a filter is applied or cleared | | onSort | function | Callback when sorting changes | | isEditable | boolean | Enable inline editing for all editable columns | | onCellEdit | (row, columnKey, value) => void | Callback when an editable cell is committed; update consumer data state here | | allowAddRow | boolean | Enable adding a new row when the last row is clicked | | onAddRow | () => void | Callback invoked when the last row is clicked and allowAddRow is true | | selectable | boolean | Enable row selection checkboxes. | | selectedIds | (string\|number)[] | Managed array of selected row IDs. | | onSelectionChange | (ids: any[]) => void | Callback for selection changes. | | renderChildView | (row: any) => ReactNode | Render function for expanded row content. | | pagination | PaginationProps | Pagination configuration. |

Column Properties

| Property | Type | Description | | --- | --- | --- | | key | string | Unique key matching the data property. | | header | string | Header display text. | | width | number \| string | Fixed width (e.g., 100 or '100px'). | | flex | number | Flex grow value (uses fr units). | | sortable | boolean | true | Whether this specific column can be sorted | | hideable | boolean | true | Whether this column can be hidden via the menu | | defaultHidden | boolean | false | Whether the column is hidden by default | | draggable | boolean | Whether this specific column can be dragged (default: true) | | resizable | boolean | Whether this specific column can be resized (default: true) | | minWidth | number | Minimum width in pixels when resizing (default: 50) | | type | 'string' \| 'number' | Data type used to determine filter operators (auto-detected if omitted) | | filterable | boolean | Whether this specific column should appear in the filter panel (default: true) | | isEditable | boolean | Enable inline editing for this column | | editor | (value, row, onChange, onCommit, onCancel) => ReactNode | Custom inline edit renderer for the cell | | render | (val, row) => ReactNode | Custom cell renderer. |

Column Management

The grid provides built-in tools for managing columns:

• Visibility: Toggle columns via the "Manage columns" dialog.
• Reordering: Drag and drop header cells to change their order, or use "Move left/right" in the column menu.
• Resizing: Hover between header cells and drag the handle to adjust column widths.
• Persistence: The grid maintains internal state for column order and widths (you can lift this state if needed by passing controlled props in future updates).
• Search & Reset: Search for columns, toggle visibility globally, or reset to defaults.

Testing

The package includes a comprehensive unit testing suite built with Vitest and React Testing Library.

To run the tests in interactive watch mode:

npm run test

To run the tests once (useful for CI/CD environments):

npm run test:run

License

MIT © Tony Tom K