React Grid Preference Engine

An enterprise-grade, highly customizable React Data Grid engine that focuses on preference management. It decouples UI from state, automatically saves grid layouts per-user (column visibility, sorting, etc.), and supports dynamic schema migrations.

Features

• Storage Agnostic: Plug in LocalStorage, Cookies, or a custom API backend.
• Multi-User Scoping: Preferences are saved using userId::gridKey.
• Dynamic Columns inference: Automatically infers column headers directly from your raw JSON data if you prefer not to configure them manually.
• Tailwind Ready: Fully customizable via classNames prop, allowing you to build completely headless-like designs.
• Schema Migrations: Built-in migration pipeline to upgrade user preferences when you push a new app version.

Installation

npm install react-grid-preference-engine lucide-react

Quick Start

1. Wrap your App with the Provider

The provider controls the storage engine and current active user.

import { GridPreferenceProvider, LocalStorageProvider } from 'react-grid-preference-engine';

function App() {
  return (
    <GridPreferenceProvider 
      initialUserId="user-123" 
      config={{ storageProvider: new LocalStorageProvider() }}
    >
      <Dashboard />
    </GridPreferenceProvider>
  );
}

2. Render a Data Grid

You can provide explicit columns, or omit them to let the engine auto-infer columns from your data.

With Explicit Columns

import { DataGrid } from 'react-grid-preference-engine';
import 'react-grid-preference-engine/style.css'; // Optional: Use base styles

const columns = [
  { id: 'id', label: 'Order ID' },
  { id: 'status', label: 'Status' }
];

const data = [
  { id: 1, status: 'Open' },
  { id: 2, status: 'Closed' }
];

function Dashboard() {
  return <DataGrid gridKey="orders-grid" title="Orders" columns={columns} data={data} />;
}

With Dynamic Auto-Inference

If you don't pass columns, the grid automatically builds them from your data keys (e.g., emailAddress becomes "Email Address").

const apiResponse = [
  { userId: 1, emailAddress: '[email protected]', role: 'admin' },
  { userId: 2, emailAddress: '[email protected]', role: 'user' }
];

function Users() {
  return <DataGrid gridKey="users-grid" title="System Users" data={apiResponse} />;
}

Styling & Customization

The grid is built to be customized. You can either use our default CSS variables, or pass your own Tailwind classes to every element using the classNames prop.

Using CSS Variables

Import the base CSS and override the variables globally:

@import 'react-grid-preference-engine/style.css';

:root {
  --gpe-bg-surface: #0b0c10;
  --gpe-border-color: rgba(255, 255, 255, 0.1);
  --gpe-text-main: #e8e9eb;
  --gpe-primary: #66fcf1;
}

Using Tailwind CSS

Completely bypass the default look by injecting Tailwind utility classes:

<DataGrid 
  gridKey="custom-tailwind-grid" 
  title="Tailwind Data" 
  data={data} 
  classNames={{
    container: "bg-gray-900 border border-gray-700 rounded-xl p-6 text-white shadow-xl",
    header: "flex justify-between items-center mb-4",
    title: "text-xl font-bold text-blue-400",
    button: "px-4 py-2 rounded-lg bg-gray-800 hover:bg-gray-700 border border-gray-600 transition",
    primaryButton: "px-4 py-2 rounded-lg bg-blue-600 hover:bg-blue-500 text-white font-medium",
    tableWrapper: "overflow-x-auto rounded-lg border border-gray-700",
    table: "min-w-full divide-y divide-gray-700",
    th: "px-6 py-3 bg-gray-800 text-left text-xs font-medium text-gray-400 uppercase tracking-wider sticky top-0",
    td: "px-6 py-4 whitespace-nowrap text-sm text-gray-300 border-b border-gray-700",
    tr: "hover:bg-gray-800/50 transition-colors"
  }}
/>

Advanced Architecture

The Custom Hook

If you want to build a completely bespoke UI from scratch, use our headless hook:

import { useGridPreferences } from 'react-grid-preference-engine';

const { 
  preferences, 
  updateVisibleColumns, 
  updateSorting 
} = useGridPreferences('my-grid');

console.log(preferences.columnVisibility);

Custom Storage Providers

Implement the StorageProvider interface to sync preferences to your backend API:

import { StorageProvider } from 'react-grid-preference-engine';

export class ApiStorageProvider implements StorageProvider {
  async get(key: string) {
    const res = await fetch(`/api/preferences/${key}`);
    return res.text();
  }
  
  async set(key: string, value: string) {
    await fetch(`/api/preferences/${key}`, { method: 'POST', body: value });
  }
  
  async remove(key: string) {
    await fetch(`/api/preferences/${key}`, { method: 'DELETE' });
  }
}