GridX - Usage Guide & API Documentation

Complete guide to using the GridX data grid component in your React application.

� Start Here!

New to GridX? Choose your path:

• 👶 I'm brand new → Read GETTING_STARTED.md (10 minutes)
• ⚡ I want code now → See QUICK_REFERENCE.md (copy-paste examples)
• 📖 I want details → Read USER_GUIDE.md (comprehensive guide)
• 📚 I'm lost → Check DOCUMENTATION.md (navigation hub)
• 🔍 I need API specs → See PROPERTY_REFERENCE.md

Total Documentation: 3,500+ lines across 6 files with 50+ working examples

📋 Table of Contents

1. Installation
2. Quick Start
3. Component Props
4. Column Configuration
5. Features & Examples
6. Advanced Usage
7. FAQ
8. 📚 Full Documentation

Installation

npm install @yashkk3640/gridx
# or
yarn add @yashkk3640/gridx

Peer Dependencies

npm install react react-dom ag-grid-community ag-grid-enterprise ag-grid-react dayjs primeflex primeicons

CSS Setup

Add these imports to your main app file:

import "ag-grid-community/dist/styles/ag-grid.css";
import "ag-grid-enterprise/dist/styles/ag-theme-alpine.css";
import "primeflex/primeflex.css";
import "primeicons/primeicons.css";

Quick Start

Basic Example

import React, { useState } from "react";
import GridX from "@yashkk3640/gridx";

const MyApp = () => {
  const [data] = useState([
    { id: 1, name: "John", email: "[email protected]", salary: 50000 },
    { id: 2, name: "Jane", email: "[email protected]", salary: 60000 },
  ]);

  const columns = [
    { ident: "id", display: "ID", type: "number", width: 60 },
    { ident: "name", display: "Name", type: "string", width: 150 },
    { ident: "email", display: "Email", type: "string", width: 200 },
    {
      ident: "salary",
      display: "Salary",
      type: "number",
      width: 120,
      prefix: "$",
    },
  ];

  return (
    <div style={{ width: "100%", height: "600px" }}>
      <GridX columns={columns} data={data} title="Employees" />
    </div>
  );
};

export default MyApp;

Component Props

Main Props

| Prop | Type | Required | Description | | ---------------------------- | --------------------- | -------- | ---------------------------------------------- | | columns | Array<ColumnConfig> | ✅ Yes | Array of column definitions | | data | Array<Object> | ✅ Yes | Array of row data objects | | title | string | ❌ No | Grid title displayed at top | | small | boolean | ❌ No | Use compact theme (default: false) | | showSelection | boolean | ❌ No | Show row selection checkboxes (default: false) | | getSelectedRows | Function | ❌ No | Callback when rows are selected | | getContextMenuItems | Function | ❌ No | Custom context menu handler | | rowHighlighter | Function | ❌ No | Function to highlight rows based on data | | editableInfo | Object | ❌ No | Object tracking edited cells | | setEditableInfo | Function | ❌ No | Setter for editableInfo state | | groupColumns | Array<GroupHeader> | ❌ No | Column grouping configuration | | exportWithFormattedNumbers | boolean | ❌ No | Export numbers with prefix/suffix |

Advanced Props

| Prop | Type | Description | | -------------------------- | ---------- | ------------------------------------------ | | getRowHeight | Function | Dynamic row height: ({ data }) => number | | onRowDoubleClicked | Function | Callback when row is double-clicked | | getContextMenuItems | Function | Custom context menu builder | | cellSelectionGridOptions | Object | ag-Grid cell selection config |

Column Configuration

Column Properties

{
  ident: "fieldName",              // Required: Property name in data object
  display: "Display Name",         // Required: Header text shown to user
  type: "string",                  // Required: Data type (see types below)
  width: 150,                      // Optional: Column width in pixels
  flex: 30,                        // Optional: Flexible width (alternative to width)
  editable: true,                  // Optional: Allow editing this column
  sortable: true,                  // Optional: Allow sorting
  sort: "asc",                     // Optional: Default sort direction ("asc" or "desc")
  pinned: "left",                  // Optional: Pin column ("left" or "right")

  // Number formatting
  prefix: "$",                     // Optional: Prefix for numbers
  suffix: " years",               // Optional: Suffix for numbers
  beautifyBigNum: true,           // Optional: Add commas to large numbers
  precision: 2,                    // Optional: Decimal places

  // Date formatting
  displayFormat: "MM/DD/YYYY",     // Date display format (dayjs tokens)
  dataFormat: "YYYY-MM-DD",        // Date input format (dayjs tokens)

  // Choices/Dropdowns
  choices: [                       // For select/dropdown columns
    "Option 1",
    "Option 2",
    // OR
    { value: "val1", label: "Display Text" }
  ],
}

Column Types

| Type | Description | Example | | ------------ | --------------------- | ---------------------- | | "string" | Text input | User name, email | | "number" | Numeric input/display | Salary, age | | "date" | Date picker | Join date, birthday | | "datetime" | Date + time picker | Created at timestamp | | "select" | Dropdown selection | Status, department | | "textarea" | Multi-line text | Description, notes | | "checkbox" | Boolean toggle | Is active, is verified | | "int" | Integer number | ID, count |

Column Configuration Examples

Basic String

{
  ident: "name",
  display: "Name",
  type: "string",
  width: 150,
  editable: true,
  sortable: true,
}

Currency Number

{
  ident: "salary",
  display: "Salary",
  type: "number",
  width: 120,
  beautifyBigNum: true,
  prefix: "$",
  precision: 2,
  sortable: true,
}

Date Selector

{
  ident: "joinDate",
  display: "Join Date",
  type: "date",
  width: 130,
  displayFormat: "MM/DD/YYYY",
  dataFormat: "YYYY-MM-DD",
  editable: true,
}

Dropdown Select

{
  ident: "status",
  display: "Status",
  type: "select",
  width: 120,
  choices: [
    { value: "Active", label: "🟢 Active" },
    { value: "Inactive", label: "🔴 Inactive" },
    { value: "OnLeave", label: "🟡 On Leave" },
  ],
  editable: true,
}

Textarea

{
  ident: "description",
  display: "Description",
  type: "textarea",
  width: 300,
  autoHeight: true,
  editable: true,
}

Features & Examples

1. Row Selection

Enable users to select multiple rows for bulk operations.

const [selectedRows, setSelectedRows] = useState({ rows: [] });

const handleDelete = () => {
  console.log("Delete:", selectedRows.rows);
};

<GridX
  columns={columns}
  data={data}
  showSelection={true}
  getSelectedRows={setSelectedRows}
/>

<button onClick={handleDelete}>
  Delete ({selectedRows.rows.length})
</button>

2. Cell Editing

Allow users to edit cell values on double-click.

const [editableInfo, setEditableInfo] = useState({
  updatedMap: new Map(),
  updated: [],
});

const handleSave = () => {
  console.log("Changed rows:", editableInfo.updated);
  // Send to API
};

<GridX
  columns={columns.map(c => ({ ...c, editable: true }))}
  data={data}
  editableInfo={editableInfo}
  setEditableInfo={setEditableInfo}
/>

<button onClick={handleSave}>
  Save Changes ({editableInfo.updated.length})
</button>

3. Sorting

Enable sorting on columns.

const columns = [
  {
    ident: "id",
    display: "ID",
    type: "number",
    sortable: true,
    sort: "asc", // Default sort
  },
  {
    ident: "salary",
    display: "Salary",
    type: "number",
    sortable: true,
    sort: "desc", // Default sort descending
  },
];

<GridX columns={columns} data={data} />;

Result: Click column headers to sort. Click again to reverse direction.

4. Row Highlighting

Color rows based on data values.

const rowHighlighter = (rowData) => {
  if (rowData.salary > 80000) return "bg-green-100";
  if (rowData.salary > 50000) return "bg-blue-100";
  return "bg-gray-100";
};

<GridX columns={columns} data={data} rowHighlighter={rowHighlighter} />;

Available Classes: bg-green-100, bg-blue-100, bg-red-100, bg-yellow-100, bg-gray-100, etc. (PrimeFlex)

5. Pinned Columns

Keep columns visible while scrolling horizontally.

const columns = [
  {
    ident: "id",
    display: "ID",
    type: "number",
    width: 60,
    pinned: "left", // Pin on left
  },
  {
    ident: "name",
    display: "Name",
    type: "string",
    width: 150,
    pinned: "left", // Pin on left
  },
  // ... other columns scroll
];

<GridX columns={columns} data={data} />;

6. Grouped Column Headers

Organize columns under header groups.

const columns = [
  { ident: "id", display: "ID", type: "number", width: 60 },
  { ident: "name", display: "Name", type: "string", width: 150 },
  { ident: "email", display: "Email", type: "string", width: 200 },
  { ident: "department", display: "Department", type: "string", width: 130 },
  { ident: "salary", display: "Salary", type: "number", width: 120 },
];

const groupHeaders = [
  {
    displayName: "Personal Info",
    children: ["id", "name", "email"],
  },
  {
    displayName: "Work Details",
    children: ["department", "salary"],
  },
];

<GridX columns={columns} groupColumns={groupHeaders} data={data} />;

7. Context Menu (Right-Click)

Add custom actions to right-click menu.

const handleContextMenu = (params) => {
  return [
    {
      name: "✏️ Edit",
      action: () => {
        console.log("Edit:", params.data);
      },
    },
    {
      name: "📋 Copy",
      action: () => {
        navigator.clipboard.writeText(JSON.stringify(params.data));
      },
    },
    {
      name: "🗑️ Delete",
      action: () => {
        const filtered = data.filter((d) => d.id !== params.data.id);
        setData(filtered);
      },
    },
    "separator",
    ...params.defaultItems, // Keep default menu items
  ];
};

<GridX
  columns={columns}
  data={data}
  getContextMenuItems={handleContextMenu}
/>;

8. Number Formatting

Display numbers with custom formatting.

const columns = [
  {
    ident: "salary",
    display: "Salary",
    type: "number",
    beautifyBigNum: true, // Add commas: 1,000,000
    prefix: "$", // Display: $1,000,000.00
    precision: 2, // 2 decimal places
  },
  {
    ident: "performance",
    display: "Performance",
    type: "number",
    suffix: "%", // Display: 95%
    precision: 1,
  },
  {
    ident: "experience",
    display: "Years",
    type: "number",
    suffix: " yrs", // Display: 5 yrs
  },
];

9. Theme Switching

Switch between compact and standard themes.

const [isCompact, setIsCompact] = useState(false);

<label>
  <input
    type="checkbox"
    checked={isCompact}
    onChange={(e) => setIsCompact(e.target.checked)}
  />
  Compact Theme
</label>

<GridX
  columns={columns}
  data={data}
  small={isCompact}  // true = compact (Balham), false = standard (Alpine)
/>

10. Dynamic Row Heights

Set row height based on data.

<GridX
  columns={columns}
  data={data}
  getRowHeight={({ data }) => {
    // Taller rows for items with description
    return data.description ? 100 : 35;
  }}
/>

Advanced Usage

Complete Real-World Example

import React, { useState } from "react";
import GridX from "@yashkk3640/gridx";

const EmployeeManager = () => {
  const [data, setData] = useState([
    {
      id: 1,
      name: "John Doe",
      email: "[email protected]",
      department: "IT",
      joinDate: "2023-01-15",
      salary: 75000,
      status: "Active",
      notes: "Senior Developer",
    },
    // ... more rows
  ]);

  const [selectedRows, setSelectedRows] = useState({ rows: [] });
  const [editableInfo, setEditableInfo] = useState({
    updatedMap: new Map(),
    updated: [],
  });

  const columns = [
    {
      ident: "id",
      display: "ID",
      type: "number",
      width: 60,
      pinned: "left",
      sortable: true,
    },
    {
      ident: "name",
      display: "Name",
      type: "string",
      width: 150,
      editable: true,
      sortable: true,
      pinned: "left",
    },
    {
      ident: "email",
      display: "Email",
      type: "string",
      width: 200,
      editable: true,
    },
    {
      ident: "department",
      display: "Department",
      type: "select",
      width: 130,
      choices: ["IT", "HR", "Finance", "Operations"],
      editable: true,
      sortable: true,
    },
    {
      ident: "joinDate",
      display: "Join Date",
      type: "date",
      width: 130,
      displayFormat: "MM/DD/YYYY",
      dataFormat: "YYYY-MM-DD",
      editable: true,
      sortable: true,
    },
    {
      ident: "salary",
      display: "Salary",
      type: "number",
      width: 120,
      beautifyBigNum: true,
      prefix: "$",
      precision: 0,
      editable: true,
      sortable: true,
      sort: "desc",
    },
    {
      ident: "status",
      display: "Status",
      type: "select",
      width: 120,
      choices: [
        { value: "Active", label: "🟢 Active" },
        { value: "Inactive", label: "🔴 Inactive" },
      ],
      editable: true,
    },
    {
      ident: "notes",
      display: "Notes",
      type: "textarea",
      width: 200,
      editable: true,
    },
  ];

  const headers = [
    { displayName: "Identification", children: ["id", "name", "email"] },
    {
      displayName: "Employment",
      children: ["department", "joinDate", "salary"],
    },
    { displayName: "Details", children: ["status", "notes"] },
  ];

  const rowHighlighter = (rowData) => {
    if (rowData.salary > 80000) return "bg-green-100";
    if (rowData.salary > 50000) return "bg-blue-100";
    return "";
  };

  const handleContextMenu = (params) => {
    return [
      {
        name: "✏️ Edit",
        action: () => console.log("Edit:", params.data),
      },
      {
        name: "🗑️ Delete",
        action: () => {
          const filtered = data.filter((d) => d.id !== params.data.id);
          setData(filtered);
        },
      },
      "separator",
      ...params.defaultItems,
    ];
  };

  const handleSaveChanges = () => {
    console.log("Saving:", editableInfo.updated);
    // API call here
  };

  const handleDelete = () => {
    const ids = selectedRows.rows.map((r) => r.id);
    const filtered = data.filter((d) => !ids.includes(d.id));
    setData(filtered);
    setSelectedRows({ rows: [] });
  };

  return (
    <div style={{ padding: "20px" }}>
      <h1>Employee Management</h1>

      <div style={{ marginBottom: "20px", display: "flex", gap: "10px" }}>
        <button
          onClick={handleDelete}
          disabled={selectedRows.rows.length === 0}
          style={{
            padding: "10px 20px",
            background: selectedRows.rows.length > 0 ? "#f44336" : "#ccc",
            color: "white",
            border: "none",
            cursor: "pointer",
          }}
        >
          Delete Selected ({selectedRows.rows.length})
        </button>

        <button
          onClick={handleSaveChanges}
          disabled={editableInfo.updated.length === 0}
          style={{
            padding: "10px 20px",
            background: editableInfo.updated.length > 0 ? "#4CAF50" : "#ccc",
            color: "white",
            border: "none",
            cursor: "pointer",
          }}
        >
          Save Changes ({editableInfo.updated.length})
        </button>
      </div>

      <div style={{ width: "100%", height: "700px" }}>
        <GridX
          columns={columns}
          groupColumns={headers}
          data={data}
          title="Employees"
          showSelection={true}
          getSelectedRows={setSelectedRows}
          editableInfo={editableInfo}
          setEditableInfo={setEditableInfo}
          rowHighlighter={rowHighlighter}
          getContextMenuItems={handleContextMenu}
          exportWithFormattedNumbers={true}
        />
      </div>
    </div>
  );
};

export default EmployeeManager;

FAQ

Q: How do I enable editing on specific columns only?

A: Add editable: true only to columns you want editable:

const columns = [
  { ident: "id", display: "ID", type: "number", editable: false },
  { ident: "name", display: "Name", type: "string", editable: true },
  { ident: "salary", display: "Salary", type: "number", editable: true },
];

Q: How do I get the edited data?

A: Use editableInfo.updated which contains an array of changed rows:

const [editableInfo, setEditableInfo] = useState({
  updatedMap: new Map(),
  updated: [],
});

// editableInfo.updated contains:
// [
//   { id: 1, name: 'Updated Name', ... },
//   { id: 2, salary: 75000, ... }
// ]

Q: How do I export to Excel?

A: The grid has built-in Excel export. Enable formatted numbers:

<GridX columns={columns} data={data} exportWithFormattedNumbers={true} />

Then use the grid's export button in the toolbar.

Q: How do I filter data?

A: Filter data before passing to the grid:

const [searchTerm, setSearchTerm] = useState("");

const filteredData = data.filter((row) =>
  row.name.toLowerCase().includes(searchTerm.toLowerCase()),
);

<GridX columns={columns} data={filteredData} />;

Q: Can I customize column widths?

A: Yes, use width for fixed or flex for flexible widths:

// Fixed width
{ ident: 'name', display: 'Name', type: 'string', width: 200 }

// Flexible width (proportional)
{ ident: 'name', display: 'Name', type: 'string', flex: 30 }

Q: How do I add row actions?

A: Use context menu with right-click:

getContextMenuItems={(params) => [
  {
    name: 'Action Name',
    action: () => {
      console.log('Row data:', params.data);
    },
  },
  ...params.defaultItems,
]}

Q: How do I use date formats?

A: Use dayjs format tokens:

{
  ident: 'joinDate',
  display: 'Join Date',
  type: 'date',
  displayFormat: 'YYYY-MM-DD',     // How to show
  dataFormat: 'YYYY-MM-DD',        // How to parse input
}

Common formats:

• DD/MM/YYYY - 25/12/2023
• MM/DD/YYYY - 12/25/2023
• YYYY-MM-DD - 2023-12-25
• MM/DD/YYYY HH:mm - 12/25/2023 14:30

Q: How do I make the grid responsive?

A: Use percentage width and flex layout:

<div style={{ display: "flex", height: "100vh" }}>
  <div style={{ flex: 1 }}>
    <GridX
      columns={columns}
      data={data}
      small={true} // Compact theme for mobile
    />
  </div>
</div>

Performance Tips

1. Large datasets: Use virtual scrolling (built-in with ag-Grid)
2. Complex rows: Use getRowHeight for dynamic heights
3. Slow edits: Debounce setEditableInfo calls
4. Memory: Don't keep entire edited data in state, just track changes
5. Re-renders: Memoize column definitions outside components

📚 Full Documentation

We've created comprehensive documentation to help you get the most out of GridX:

Documentation Files

| File | Purpose | Time | Best For | | -------------------------------------------------- | ----------------------------------------- | ------ | ------------------------ | | GETTING_STARTED.md | Beginner-friendly setup guide | 10 min | First-time users | | QUICK_REFERENCE.md | Copy-paste code snippets & cheat sheets | 5 min | Quick lookups | | USER_GUIDE.md | Comprehensive feature guide with examples | 30 min | Learning all features | | PROPERTY_REFERENCE.md | Complete API reference with defaults | 15 min | Finding exact properties | | DOCUMENTATION.md | Navigation hub & learning paths | 2 min | Finding what you need | | DOCS_OVERVIEW.md | Overview of all documentation | 3 min | Understanding structure |

Quick Links

Installation & Setup

• GETTING_STARTED.md

First Grid (5 minutes)

• GETTING_STARTED.md
• QUICK_REFERENCE.md

All Features Explained

• USER_GUIDE.md

Column Types & Configuration

• USER_GUIDE.md
• QUICK_REFERENCE.md

Real-World Examples

• USER_GUIDE.md - 5 examples
• QUICK_REFERENCE.md - 10 snippets

Master-Child Grids

• USER_GUIDE.md

Troubleshooting

• GETTING_STARTED.md
• QUICK_REFERENCE.md

Documentation Highlights

📊 3,500+ lines of documentation

• Complete API reference
• 50+ working code examples
• 6 different guides for different needs
• Real-world use cases
• Best practices & tips

✅ Features Covered

• Installation & setup
• Column configuration (8 types)
• Row selection & bulk operations
• Cell editing & change tracking
• Row highlighting & styling
• Column grouping & pinning
• Sorting & filtering
• Date & number formatting
• Dropdowns & checkboxes
• Master-child hierarchies
• Context menus
• Excel export

🎯 Learning Paths

• Beginner (1-2 hours)
• Intermediate (2-4 hours)
• Advanced (4+ hours)

💡 Quick Reference

• Property cheat sheets
• Column type guide
• Common patterns
• CSS classes
• Troubleshooting guide

How to Use the Documentation

1. Just getting started? → GETTING_STARTED.md
2. Need code quickly? → QUICK_REFERENCE.md
3. Want to learn all features? → USER_GUIDE.md
4. Looking for a specific prop? → PROPERTY_REFERENCE.md
5. Don't know where to look? → DOCUMENTATION.md

🎓 Learning Paths

Beginner Path (1-2 hours)

1. Read GETTING_STARTED.md (10 min)
2. Create your first grid (10 min)
3. Try basic features (20 min)
4. Read key features in USER_GUIDE.md (20 min)

Developer Path (1 hour)

1. Skim GETTING_STARTED.md (5 min)
2. Copy example from QUICK_REFERENCE.md (5 min)
3. Explore USER_GUIDE.md for your use case (20 min)
4. Reference PROPERTY_REFERENCE.md as needed

Power User Path (2+ hours)

1. Read GETTING_STARTED.md (10 min)
2. Study USER_GUIDE.md (30 min)
3. Review PROPERTY_REFERENCE.md (15 min)
4. Build your app using examples (60+ min)

Additional Resources

• Storybook Examples: See src/stories/GridX.stories.jsx for 13 working examples
• ag-Grid Docs: https://www.ag-grid.com/react-data-grid/
• dayjs Tokens: https://day.js.org/docs/en/parse/string-format
• PrimeFlex Classes: https://www.primefaces.org/primeflex/

Version: 0.0.0-rc1
Last Updated: January 2026
License: See package.json