syncfusion-blazor-datagrid

What this skill does

***

# Implementing Syncfusion Blazor DataGrid

The Syncfusion Blazor DataGrid (`SfGrid<TValue>`) is a high-performance, feature-rich component for displaying and manipulating tabular data. It supports data binding, sorting, filtering, grouping, paging, editing, selection, aggregates, export, virtual/infinite scrolling, templates, and more.

**NuGet:** `Syncfusion.Blazor.Grid` + `Syncfusion.Blazor.Themes`  
**Namespace:** `Syncfusion.Blazor.Grids`

## When to Use This Skill

Use this skill when you need to:
- Set up and configure a DataGrid in Blazor Server, WebAssembly, Web App, or MAUI
- Bind local or remote data (OData, HTTP, SfDataManager)
- Configure columns (type, format, template, frozen, reorder, resize, chooser)
- Implement sorting, filtering (FilterBar/Menu/Excel/CheckBox), or searching
- Enable grouping with lazy load or caption templates
- Configure paging with custom templates or SfPager
- Set up virtual scrolling, infinite scrolling for large datasets
- Implement editing (Normal/Dialog/Batch/Command column) with validation
- Configure selection (row, cell, checkbox) with programmatic control
- Use clipboard copy, AutoFill, or Paste features
- Add aggregates (footer, group, caption, reactive)
- Use row/column templates, detail template, row drag-drop
- Configure toolbar, context menu, column menu, column chooser
- Export data to Excel or PDF
- Manage print functionality
- Optimize performance (SetRowDataAsync, PreventRender)
- Handle DataGrid events
- Manage state persistence (EnablePersistence)
- Customize styling and appearance
- Enable adaptive UI for mobile/responsive layouts

# 🔒 Mandatory Key Rules

These rules govern how this skill MUST behave. They are mandatory and must be strictly followed.

## 1. Purpose and Responsibility

Your responsibility is to interpret any natural‑language user request and provide:

*   Accurate
*   Complete
*   Validated

information about all supported aspects of the **Syncfusion Blazor DataGrid**, including:

*   Public APIs
*   Properties
*   Events
*   Features
*   Behaviors

## 2. Accuracy and API Compliance

The Skill MUST:

*   Use **only officially supported** Syncfusion DataGrid features.
*   **NEVER** invent APIs, methods, properties, events, behaviors, or future features.
*   **NEVER** provide unsupported or hypothetical code samples.
*   ALWAYS follow official Syncfusion component design patterns.

If a feature is **not supported**:

*   Clearly state the limitation.
*   Suggest a supported alternative when possible.

## 3. Interpreting Natural-Language Requests

When user requests are incomplete:

*   Infer reasonable assumptions using official Grid best practices.
*   Fill missing gaps with accurate and relevant information.
*   Request clarification **only** when essential.

## 4. Response Quality Requirements

Every response MUST:

*   Be technically accurate
*   Be complete and well‑structured
*   Include required dependencies and configuration notes
*   Follow real, documented Syncfusion API behavior
*   Avoid contradictions or ambiguity

## 5. Handling Unsupported User Requests

If the user asks for an unsupported capability:

*   Explicitly state that it is not supported
*   Suggest official alternatives or valid workarounds
*   NEVER simulate or fabricate impossible functionality

## 6. Design Pattern Enforcement

The Skill MUST follow Syncfusion official patterns, including:

*   Correct component structure (`SfGrid`, `GridColumn`, `GridEditSettings`, etc.)
*   Proper async event and API usage
*   Valid configuration properties and enums
*   Supported data‑binding approaches
*   Real event patterns and names

## 7. Quality, Completeness & Reliability

The Skill MUST:

*   Use only validated and real Grid capabilities
*   Provide actionable and implementation‑ready guidance
*   Ensure clarity so users can follow without guesswork
*   Maintain clean, readable, and professional formatting

## 8. No-Hallucination Safeguard

The Skill MUST NOT:

*   Invent non‑existent APIs or behavior
*   Suggest unsupported modes, features, or configuration
*   Provide incorrect, misleading, or unverifiable code
*   Describe undocumented internal behavior

If unsure:

*   Ask for clarification **OR**
*   Clearly state the limitation

## 9. Event Name Verification Requirement

**CRITICAL:** Event names MUST be verified against `references/events.md` BEFORE providing code examples. All grid events MUST be defined inside the `<GridEvents>` component

**Common Mistakes to Avoid:**

*   ❌ `OnSortChange` - Does NOT exist. Use `Sorting`, `Sorted` instead
*   ❌ `OnFilterChange` - Does NOT exist. Use `Filtering`, `Filtered` instead
*   ❌ `OnPageChange` - Does NOT exist. Use `PageChanging`, `PageChanged` instead
*   ❌ `OnGroupChange` - Does NOT exist. Use `Grouping`, `Grouped` instead

**Rule:** ALWAYS cross-reference `references/events.md` for:

*   Exact event names (case-sensitive)
*   Event argument types
*   Whether events are cancelable
*   When they fire (before/after operation)

**Verification Checklist Before Providing Event Code:**

1. Check if event name exists in `references/events.md`
2. Verify the correct `EventArgs` type
3. Confirm `Cancelable` status (✅ or ❌)
4. Test against actual Syncfusion documentation
5. Never assume naming conventions (e.g., `On` prefix, `Change` suffix)

---

## Strict Rules for Grid Events

### 1. **Event Handlers MUST be in `<GridEvents>` Component**
   - ✅ Define ALL event handlers inside `<GridEvents TValue="YourType">`
   - ✅ Use the exact event names as properties (e.g., `DataBound`, `RowSelecting`, `Grouped`)
   - ❌ DO NOT use `@onEventName` syntax on `<SfGrid>`
   - ❌ DO NOT define event handlers on any root element

### 2. **Correct Event Handler Signatures**
   - ✅ Use `async Task` for event handlers
   - ✅ Event handlers may have specific parameter types (e.g., `GridEventArgs`, `RowSelectEventArgs`)
   - ✅ Some events have no parameters (e.g., `DataBound()`, `Created()`)
   - ❌ Do not use synchronous `void` methods for async operations

### 3. **API Method Calls MUST NOT be in Lifecycle Events**
   - ❌ DO NOT call API methods in `OnInitialized()`
   - ❌ DO NOT call API methods in `OnAfterRenderAsync()`
   - ❌ DO NOT call API methods in `OnParametersSet()`
   - ✅ ONLY call API methods in response to user interactions (button clicks, dropdown changes, etc.)
   - ✅ API methods CAN be called inside GridEvents handlers

### 4. **Use Async/Await Pattern**
   - ✅ Always use `await` with async API methods
   - ✅ Define event handlers as `async Task`
   - ✅ Mark code block methods as `async Task`
   - ❌ Do not use synchronous method calls for async operations

### 5. **Grid Reference Required for API Calls**
   - ✅ Use `@ref="Grid"` to get the Grid instance
   - ✅ Use the reference to call API methods (e.g., `await Grid.GroupColumnAsync()`)
   - ❌ Do not attempt to call methods without a reference

### 6. **Event Types Must Match GridEvents TValue**
   - ✅ Set `TValue="YourDataType"` to match your data model
   - ✅ All event handlers will be properly typed with this model
   - ❌ Do not use generic or wrong type for TValue

---

## Navigation Guide

### Setup & Getting Started
📄 **Read:** [references/getting-started.md](references/getting-started.md)
- NuGet install, `_Imports.razor`, `Program.cs`, theme/script setup, basic grid

📄 **Read:** [references/getting-started-app-types.md](references/getting-started-app-types.md)
- Server App, Web App (Auto/WASM), MAUI variants

### Data
📄 **Read:** [references/data-binding.md](references/data-binding.md)
- Local (List, ExpandoObject, DynamicObject, DataTable, ObservableCollection)

### Connecting to Adaptors (Remote Data)
📄 **Read:** [references/odatav4-adaptor.md](references/odatav4-adaptor.md)
- OData V4 service setup, ODataConventionModelBuilder, [EnableQuery], automatic $filter/$orderby/$skip/$top, CRUD with PATCH/DELETE

📄 **Read:** [references/web-api-adaptor.md](references/web-api-adaptor.md)
- Web API with {