Skip to content

yashkk3640/gridx

BranchesTags

Repository files navigation

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:

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: "john@example.com", salary: 50000 },
    { id: 2, name: "Jane", email: "jane@example.com", 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: "john@company.com",
      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

First Grid (5 minutes)

All Features Explained

Column Types & Configuration

Real-World Examples

Master-Child Grids

Troubleshooting

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

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

About

Library to render simple and/or editable grid using ag-grid

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages