free-grid-react

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

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.
• 🎨 MUI-Inspired: Clean, professional aesthetic out of the box.
• 🛠️ 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.
• 🧺 Column Management: Hide/Show individual columns via header menu.
• ⚙️ 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() {
  return (
    <Grid
      data={data}
      columns={columns}
      selectable={true}
      pagination={{ total: 2, 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). | | 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 | | onSort | function | - | Callback when sorting changes | | 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 | true | Whether this specific column can be dragged | | resizable | boolean | true | Whether this specific column can be resized | | minWidth | number | 50 | Minimum width in pixels when resizing | | 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.

License

MIT © Tony Tom K