@rg-grid/rg-grid

RGGrid is a production-grade React + TypeScript data grid built for internal tools and business applications.

It follows an API-first, logic-first architecture — all behavior runs through deterministic feature plugins, while the UI remains a thin, replaceable render layer.

No wrapper components. No hidden magic. Fully extensible.

🌐 Live Demo

👉 https://rg-grid.vercel.app/

🚀 Quick Start

Install

npm install @rg-grid/rg-grid
npm install react react-dom

Import Styles

import "@rg-grid/rg-grid/styles.css";

Tailwind is not required in consumer applications.

Basic Usage

import "@rg-grid/rg-grid/styles.css";
import { RGGrid } from "@rg-grid/rg-grid";
import type { Column } from "@rg-grid/rg-grid";

type Account = {
  id: number;
  company: string;
  owner: string;
  mrr: number;
  status: "draft" | "review" | "approved" | "rejected";
};

const columns: Column<Account>[] = [
  { key: "id", label: "ID", sortable: true, width: 80, align: "center" },
  { key: "company", label: "Company", sortable: true, showFilter: true },
  { key: "owner", label: "Owner", sortable: true },
  { key: "mrr", label: "MRR", sortable: true, align: "right" },
  { key: "status", label: "Status", sortable: true, showFilter: true },
];

const data: Account[] = [
  { id: 1, company: "Northwind", owner: "Ava", mrr: 12000, status: "review" },
  { id: 2, company: "Nimbus", owner: "Noah", mrr: 5200, status: "draft" },
];

export default function Page() {
  return (
    <RGGrid
      data={data}
      columns={columns}
      defaultPageSize={10}
      sortable
      resizable
      pagination
      rowReorderable
      showRowDragHandle
      getRowId={(row) => row.id}
    />
  );
}

✨ Feature Highlights

Core Grid

• Sorting
• Column + global filtering
• Pagination
• Column resizing
• Column reordering (drag & drop)
• Row reordering
• Editable cells
• URL state sync (page, pageSize)
• SSR-safe behavior

Advanced Features

• Deterministic plugin system
• Rules engine (sync + async)
• Audit trail
• Workflow states + transitions
• Tree / hierarchical rows (accordion)
• Light / Dark theme
• Token-based design system
• Imperative plugin API registry

🧠 Architecture

Full guide:
📄 docs/architecture.md

Deterministic Data Pipeline

Raw Data
   ↓
CoreRow
   ↓
Feature Plugins (ordered, priority-based)
   ↓
ViewRow
   ↓
Render Layer

RGGrid is designed so features compose cleanly without wrappers.

🔎 Common Usage Patterns

Rules Engine

import type { Rule } from "@rg-grid/rg-grid";

const rules: Rule<Account>[] = [
  {
    column: "mrr",
    condition: (value) => Number(value) < 0,
    action: "error",
    message: "MRR cannot be negative",
  },
];

<RGGrid data={data} columns={columns} rules={rules} />;

Supports sync + async validations.

Audit + Imperative API

import { useRef } from "react";
import { RGGrid } from "@rg-grid/rg-grid";
import type { RGGridHandle } from "@rg-grid/rg-grid";

const gridRef = useRef<RGGridHandle>(null);

<RGGrid
  ref={gridRef}
  data={data}
  columns={columns}
  editable
  audit={{ enabled: true, getUser: () => "[email protected]" }}
  showRecentEdits
/>;

const logs = gridRef.current?.getAuditLogs?.() ?? [];
const auditApi = gridRef.current?.getPlugin?.("audit");
const sameLogs = auditApi?.getAuditLogs?.() ?? [];

Workflow

const workflow = {
  column: "status",
  states: ["draft", "review", "approved", "rejected"],
  transitions: {
    draft: ["review"],
    review: ["approved", "rejected"],
    rejected: ["review"],
  },
};

<RGGrid
  data={data}
  columns={columns}
  workflow={workflow}
  onStateChange={(row, state) => {
    console.log("workflow changed", row, state);
  }}
/>;

🌳 Tree / Hierarchical Rows

Fully compatible with sorting, filtering, pagination, and row reordering.

Flat Structure (Manager → Employee)

type Employee = {
  id: number;
  managerId?: number;
  name: string;
  role: string;
};

<RGGrid
  data={employees}
  columns={columns}
  tree={{
    getId: (row) => row.id,
    getParentId: (row) => row.managerId,
    defaultExpanded: false,
  }}
/>;

Nested Structure (Album → Tracks)

<RGGrid
  data={albums}
  columns={columns}
  tree={{
    childrenKey: "tracks",
    getId: (row) => row.id,
    defaultExpanded: true,
    indentSize: 16,
  }}
/>

🎨 Theming

Options

• theme="light" or theme="dark"
• Wrapper classes: .rg-theme-light / .rg-theme-dark
• Disable built-in switch: showThemeSwitch={false}

<div className="rg-theme-dark">
  <RGGrid data={data} columns={columns} showThemeSwitch={false} />
</div>

📦 Main Exports

import { RGGrid, AdvancedTable, DarkLightModeSwitch } from "@rg-grid/rg-grid";

import {
  useFeaturePipeline,
  useTreeFeaturePlugin,
  useFilteringFeaturePlugin,
  useSortingFeaturePlugin,
  useRowReorderFeaturePlugin,
  usePaginationFeaturePlugin,
  useRulesPlugin,
  useAuditPlugin,
  useWorkflowPlugin,
} from "@rg-grid/rg-grid";

import type {
  RGGridProps,
  RGGridHandle,
  Column,
  FeaturePlugin,
  TreeConfig,
  Rule,
  AuditLog,
  WorkflowConfig,
} from "@rg-grid/rg-grid";

🛡 SSR & Framework Support

• SSR safe (Next.js compatible)
• No hard dependency on router
• URL sync uses window.history.replaceState
• Browser APIs guarded (window, localStorage)

💡 Design Principles

• API-first
• Logic-first
• Deterministic behavior
• No wrapper components
• Plugin extensibility
• Enterprise-ready
• Composable features

☕ Support Development

If RGGrid helps your team:

👉 https://buymeacoffee.com/rajugundu