ag-grid

name	ag-grid
description	Advanced data tables with AG Grid. Trigger: When implementing AG Grid tables, configuring features, or creating custom cell renderers.
license	Apache 2.0
metadata	{"version":"1.1","type":"library","skills":["react"],"dependencies":{"ag-grid-community":">=29.0.0 <31.0.0","ag-grid-react":">=29.0.0 <31.0.0","react":">=17.0.0 <19.0.0","typescript":">=5.0.0 <6.0.0"},"allowed-tools":["file-reader"]}

AG Grid

React data tables with sorting, filtering, pagination, inline editing, and Excel-like features. TypeScript typing, accessibility, and virtualization.

Examples use ag-grid-react. Column config API (ColDef, onGridReady) is framework-agnostic — adapt cell renderers to your framework's component syntax for Angular/Vue.

When to Use

• Data tables with sorting/filtering/pagination
• Editable grids with inline editing
• Complex grids with grouping/aggregation
• High-performance with virtualization
• Excel-like functionality

Don't use for:

• Simple tables (use HTML/MUI Table)
• Non-tabular viz (use charts)
• Mobile-first (consider simpler)

---

Critical Patterns

✅ REQUIRED: Use TypeScript Interfaces for Type Safety

// ✅ CORRECT: Typed column definitions
import { ColDef } from "ag-grid-community";

interface RowData {
  id: number;
  name: string;
}

const columnDefs: ColDef<RowData>[] = [{ field: "id" }, { field: "name" }];

// ❌ WRONG: Untyped columns
const columnDefs = [{ field: "id" }, { field: "name" }];

✅ REQUIRED: Use defaultColDef for Common Settings

// ✅ CORRECT: DRY column configuration
const defaultColDef: ColDef = {
  sortable: true,
  filter: true,
  resizable: true,
};

<AgGridReact defaultColDef={defaultColDef} />

// ❌ WRONG: Repeating config for each column
const columnDefs = [
  { field: 'id', sortable: true, filter: true, resizable: true },
  { field: 'name', sortable: true, filter: true, resizable: true },
];

✅ REQUIRED: Enable Accessibility Features

// ✅ CORRECT: Accessibility enabled
<AgGridReact
  enableAccessibility={true}
  suppressMenuHide={false}
/>

---

Conventions

AG Grid Specific

• TypeScript interfaces for columns
• Cell renderers for custom content
• Apply accessibility best practices: keyboard navigation, screen reader support, ARIA attributes
• Built-in features over custom
• Handle loading/error states

---

Decision Tree

Custom cells?
  → Use cellRenderer/cellRendererFramework

Editable?
  → editable: true, handle onCellValueChanged

Filtering?
  → filter: true or specify type (agTextColumnFilter, agNumberColumnFilter)

Large dataset?
  → rowModelType: 'infinite' for server pagination

Grouping?
  → rowGroup: true on columns

Export?
  → exportDataAsCsv()/exportDataAsExcel()

Performance?
  → Virtualization (default), immutableData: true for React

---

Example

import { ColDef } from 'ag-grid-community';
import { AgGridReact } from 'ag-grid-react';

interface RowData {
  id: number;
  name: string;
  value: number;
}

const columnDefs: ColDef<RowData>[] = [
  { field: 'id', headerName: 'ID' },
  { field: 'name', headerName: 'Name', sortable: true },
  { field: 'value', headerName: 'Value', filter: 'agNumberColumnFilter' }
];

<AgGridReact<RowData>
  rowData={data}
  columnDefs={columnDefs}
  defaultColDef={{ flex: 1, minWidth: 100 }}
/>

---

Edge Cases

• Empty data → appropriate messaging
• Loading states during fetch
• Error boundaries for failures
• Resize events properly
• Test keyboard navigation

---

Resources

• https://www.ag-grid.com/react-data-grid/
• https://www.ag-grid.com/react-data-grid/accessibility/