syncfusion-pure-react-grid

Syncfusion® React Data Grid

A knowledge and decision skill for everything in @syncfusion/react-grid (the pure-React Syncfusion grid, React 17+). It bundles the full feature surface, the conventions the library expects, and the guardrails that keep generated code safe.

The skill is source-of-truth aware: every feature, prop, enum, event, and module listed here comes from the official Syncfusion React Data Grid documentation. Nothing here is invented. When a feature is in flux or has known limitations, this skill calls that out explicitly.

How to use this skill

1. Identify the user's intent — are they scaffolding a new grid, configuring an existing one, debugging, or generating new UI on top of it?
2. Pick the right reference file(s) from the table below. Read each before authoring code in that area — references are the authoritative detail surface.
3. Always pass the baseline settings the grid expects (see "Mandatory default settings" below). Missing modules, missing primary key, or missing enableDevMode={false} silently break features.
4. Apply guardrails when generating or modifying code. The full enforcement rules live in references/guardrails-applied.md.

Mandatory default settings (apply to every Grid)

These settings are mandatory in every grid you produce unless the user explicitly opts out:

import {
  Grid, Columns, Column, /* all features you plan to use */
  FilterModule, PagerModule, /* etc. */
  /* all settings/enums/events relevant to the feature mix */
} from '@syncfusion/react-grid';

const modules = { FilterModule, PagerModule /* add as needed */ };

<Grid
  dataSource={data}
  modules={modules}
  enableDevMode={false}
  // ...other feature-level settings
>

• Modules map: every non-built-in feature requires its module — see references/modules-and-imports.md. GridAllModule may be used for prototypes; production should pick single modules.
• enableDevMode={false}: suppresses diagnostic console output. Required on every example in the official docs.
• Primary key: define exactly one column with isPrimaryKey={true} whenever the user enables editing, selection persistence, setCellValue/setRowData, autofill, clipboard paste, or checkbox selection. Without it, edits/deletes misbehave (first-row-only writes, selection doesn't persist across paging).
• Module registration first: a feature that needs XModule but lacks it produces a silent runtime error, often mistaken for a data bug.

Reference file index

Load the relevant reference(s) before authoring code in that area. Files are scoped — load only what applies.

Concern	Reference file
Install, modules map, all named exports, enums, settings types	references/modules-and-imports.md
Columns: configuration, types, format, templates, headers, resizing, reorder, menu, chooser, spanning, dynamic state	references/columns.md
Cells: clip mode, text wrap, styling, grid lines, expressions, HTML content	references/cells.md
Rows: rows, templates, row template, row numbers, row drag-and-drop, row spanning	references/rows.md
Data binding: local, remote (DataManager/adaptors), custom onDataRequest, empty-record template	references/data-binding.md
Paging	references/paging.md
Sorting	references/sorting.md
Filtering (all four modes), operators, programmatic	references/filtering.md
Searching	references/searching.md
Editing — Configuration, all modes, edit types, validation, command column	references/editing.md
Editing — Inline, Popup, PopupTemplate, Cell, custom-edit	references/editing-modes.md
Selection — Row, Cell, Checkbox, Conditional, Cell selection type	references/selection.md
Grouping + aggregates	references/grouping-and-aggregates.md
Virtualization, virtual scroll, infinite scroll — performance data strategies	references/performance-and-scrolling.md
Autofill, Clipboard, Context Menu, Toolbar	references/interactivity.md
Master/Detail — simple detailRowTemplate and relational detailCellRendererParams	references/master-detail.md
Real-time grid (interval-driven updates, setCellValue + currentViewData)	references/real-time-grid.md
Print, PDF Export, Excel Export — the three hook-based exports	references/exports.md
Tree Data — nested / self-referential hierarchical rendering, sorting, filtering, aggregates	references/tree-data.md
Pivot view — pivotSettings (rows / columns / values), result columns, customisation callbacks	references/pivot.md
Formulas — allowFormula, expression engine, custom functions, A1 notation, error codes	references/formulas.md
Tool Panel — side bar of columns / filters / editing panels and custom panels	references/tool-panel.md
Integrated Charts in Grid — GridChart companion, chart types, exports, context-menu trigger	references/integrated-charts.md
Updating Data — sync vs async CRUD, bulk/batch, high-frequency streaming update patterns	references/updating-data.md
Accessibility (WCAG roles/attrs, keyboard map, known gaps)	references/accessibility.md
Globalization (L10n, loadCldr, Provider, enableRtl, locale prop)	references/globalization.md
Theming (Material/Bootstrap/Tailwind, light/dark, --sf-* variables)	references/theming.md
Security, compatibility, browser support	references/security-compatibility.md
Guardrails integrated into generated code	references/guardrails-applied.md

Imperative API surface (GridRef)

gridRef.current?.<method> is the public imperative handle. Key methods (full list with signatures in references/imperative-api.md — load that file when generating command-button code, custom toolbars, or programmatic mutations):

• Sort: sortByColumn, removeSortColumn, clearSort and async variants sortColumnAsync, removeSortColumnAsync, clearSortingAsync
• Filter: filterByColumn, clearFilter and async variants filterByColumnAsync, clearFilteringAsync
• Search: search, searchAsync, getData
• Paging: goToPage, goToPageAsync, pagerRef.totalRecordsCount
• Selection: selectRow, selectRows, clearRowSelection, clearSelection, clearCellSelection, getSelectedRecords, getSelectedRowIndexes
• Editing: addRecord, addRecordAsync, editRecord, updateRecord, updateRecordAsync, setCellValue, setCellValueAsync, setRowData, setRowDataAsync, deleteRecord, deleteRecordAsync, saveDataChanges, cancelDataChanges, editCell, saveCellChanges, cancelCellChanges
• Editing — batch: saveBatchChanges, cancelBatchChanges, getBatchQueue, getConfirmBatch
• Editing — bulk & undo/redo: saveBulkChanges, undo, redo, getUndoActionsCount, getRedoActionsCount, clearUndoRedoHistory
• Grouping: groupColumnAsync, ungroupColumnAsync, clearGroupingAsync
• Columns: getColumnByField, resizeColumns, reorderColumns, openColumnChooser, getColumns, pinColumn, unpinColumn
• Rows: pinRows, unpinRows
• Autofill: applyFill
• Clipboard: copyToClipboard, pasteFromClipboard, cutToClipboard
• Layout: refresh
• Streaming: currentViewData

Use a useRef<GridRef>(null) and always chain optional-call: gridRef.current?.method?.().

Decision patterns (use these to pick features, don't memorize props)

When the user says... → reach for:

• "Filter my table" → start with filterSettings.type: 'FilterBar' (default). Move to 'Menu' for AND/OR compounds, 'Excel' for Excel-style checklist, 'CheckBox' for a unified BA-only dropdown.
• "Sort by clicking headers" → sortSettings.enabled = true (default mode Multiple, ctrl-click to add, shift-click to remove).
• "Edit inline like Excel" → editSettings = { mode: 'Cell', allowEdit: true } + editCell / saveCellChanges.
• "Edit one row at a time" → editSettings = { mode: 'Normal', allowEdit: true, allowAdd: true, allowDelete: true } + toolbar.
• "Show a modal form for editing" → mode: 'Popup' + popupSettings. Fully custom form → mode: 'PopupTemplate' + popupTemplate.
• "Bulk delete with checkboxes" → <Column type='checkbox' width='40' /> + selectionSettings.persistSelection (auto-enabled) + toolbar Delete.
• "Render thousands of rows fast" → virtualizationSettings.enabled = true + fixed rowHeight + getRowHeight only if needed.
• "Stream live data" → setCellValue(pk, field, value) with fixed rowHeight and enableHover={false}.
• "Master/detail rows" → isMasterDetail + detailRowTemplate for simple cases; detailCellRendererParams for relational binding.
• "Hierarchical / tree / org chart" → isTreeMode={true} + TreeDataModule (see references/tree-data.md).
• "Pivot / multi-dimension summary" → pivotSettings + PivotModule (see references/pivot.md).
• "Spreadsheet-style formula cells" → Column.allowFormula + FormulaModule (see references/formulas.md).
• "Show a side panel of column / filter / edit / custom tools" → sideBar + the appropriate *ToolPanelModule (see references/tool-panel.md).
• "Show a chart from grid data" → install @syncfusion/react-grid-chart and render <GridChart ref> as a sibling (see references/integrated-charts.md).
• "Stream live data / high-frequency updates" → setCellValue + fixed rowHeight + disabled hover/selection/keyboard (see references/real-time-grid.md and references/updating-data.md).
• "Print / PDF / Excel" → useGridPrint, useGridPdfExport, useGridExcelExport hooks (these are the public API; pass gridRef).
• "Right-to-left" → <Provider locale='ar'><Grid enableRtl /></Provider>.

Guardrails applied

This skill follows the same enforcement model as the project's guardrails skill: it tells you when each check applies and how to apply it, without re-teaching lint/test/security concepts the agent already knows.

When generating, editing, or modifying a React Data Grid, follow references/guardrails-applied.md. The summary rules:

• Confirm isPrimaryKey exists before turning on editing, selection persistence, setCellValue, autofill, clipboard, or checkbox selection.
• Never edit template/template/cellClass/valueAccessor callbacks that are not memoized (useCallback/memo) — these re-run on every render and degrade scroll perf.
• Always memoize the <Grid> JSX with useMemo keyed on data + handler identities for stable rendering.
• Use fixed rowHeight for any dataset over ~1k rows, any streaming grid, or any virtualized setup. Avoid autoHeight on columns that contain templates (it disables column virtualization).
• Migration/aggregate moments: integrate the change — register modules, import named exports, wire CSS theme at App.css, ensure the detailRowTemplate is reachable from the parent. Integration > correctness.
• Bug fix retrospectives for grid features: detection gap (silent feature failures come from missing modules / missing PK), prevention (add an explicit module registration test or PK assertion), pattern scan (sibling columns missing isPrimaryKey).
• Confirm sensitive operations (mass delete, clearFilter([]) wiping all filters, persistence toggles that affect server payloads) before executing.
• Inject guardrail guidance into UI critical paths: never mass-delete from the server without a confirmation dialog coming from editSettings.confirmOnDelete.

Output conventions for generated code

When generating React Data Grid code, always:

• Import everything explicitly from @syncfusion/react-grid (do not deep-import internal paths unless necessary for DetailCellRendererParams, GetDetailRowDataParams, GroupSettings).
• Use enableDevMode={false} on every <Grid>.
• Register modules in a useMemo or module-scope const — never inline.
• Wrap templates in useCallback, template components in React.memo.
• Memoize the <Grid> JSX with useMemo.
• Set Column.type explicitly when the first cell value could be null/undefined, otherwise the wrong default editor/filter is inferred.
• Mark exactly one column as isPrimaryKey whenever the grid mutates data.
• Pair selectionSettings.type = SelectionType.Cell with cellSelectionType setting whenever autofill is enabled.

When NOT to use this skill

• Syncfusion Angular, Vue, Blazor, ASP.NET MVC, vanilla JS grids → wrong framework.
• Other Syncfusion React components (chart, scheduler, gantt, kanban, rich text editor, diagram, etc.) → not in scope. Use a different, dedicated skill.
• Non-React data tables (TanStack Table, AG Grid community edition, Mantine DataTable, MUI X DataGrid) → out of scope.

Quick reference card

// Minimum viable grid (built-in sorting + paging + filter-bar + search)
import {
  Grid, Columns, Column,
  FilterModule, PagerModule, SearchModule,
  SortSettings, FilterSettings, PageSettings, SearchSettings,
} from '@syncfusion/react-grid';

const modules = { FilterModule, PagerModule, SearchModule };

const [sort]    = useState<SortSettings>({ enabled: true });
const [page]    = useState<PageSettings>({ enabled: true, pageSize: 12 });
const [filter]  = useState<FilterSettings>({ enabled: true });
const [search]  = useState<SearchSettings>({ enabled: true });

<Grid
  dataSource={rows}
  modules={modules}
  enableDevMode={false}
  sortSettings={sort} filterSettings={filter} pageSettings={page} searchSettings={search}
  toolbar={['Search']}
>
  <Columns>
    <Column field="id" headerText="ID" isPrimaryKey />
    {/* ... other columns */}
  </Columns>
</Grid>