syncfusion-react-query-builder

# Implementing Syncfusion React Query Builder A comprehensive guide for implementing and customizing the Syncfusion React Query Builder component. The Query Builder is a powerful UI component for creating and managing complex filter conditions, with support for rule-based queries, multiple data types, SQL generation, and extensive customization options. ## Component Overview The Query Builder component provides a graphical interface for creating and editing complex filter rules. It outputs structured JSON that can be converted to SQL, Mongo queries, or custom predicates for filtering data. Key capabilities include: - **Rule Management:** Create, edit, delete, and nest rules and groups - **Multiple Data Types:** Support for string, number, date, boolean, and custom types - **Operator Support:** 16+ built-in operators (equal, contains, between, in, etc.) - **Query Conversion:** Convert to SQL, Mongo, or parameterized queries - **Customization:** Custom templates, themes, and styling - **Accessibility:** WCAG compliant with keyboard navigation and screen reader support - **Advanced Features:** Drag-and-drop, state persistence, cloning, locking ## Documentation and Navigation Guide ### Getting Started 📄 **Read:** [references/getting-started.md](references/getting-started.md) - Installation and package setup - Basic component initialization - CSS imports and themes - Creating your first Query Builder - Column definition basics - Running the application ### Columns and Operators 📄 **Read:** [references/columns-and-operators.md](references/columns-and-operators.md) - Defining column schema with ColumnsModel - Auto-generating columns from data sources - Configuring labels and field mappings - Supported operators by data type - Setting step and format properties - Column validation configuration ### Data Binding 📄 **Read:** [references/data-binding.md](references/data-binding.md) - Binding local data arrays - Remote data with DataManager - ODataV4Adaptor integration - Dynamic data updates - Using DataManager with Query Builder - Handling data source changes ### Rules and Filtering 📄 **Read:** [references/rules-and-filtering.md](references/rules-and-filtering.md) - Understanding rule structure (RuleModel) - Creating rules programmatically with addRules - Creating groups with addGroups - Deleting rules and groups - Managing nested rule hierarchies - Drag-and-drop rule management - Show buttons configuration ### Query Conversion 📄 **Read:** [references/query-conversion.md](references/query-conversion.md) - Converting rules to SQL with getSqlFromRules - Generating Mongo queries with getMongoQuery - Creating parameterized SQL queries - Named parameter SQL generation - Converting predicates for DataManager - Importing rules from SQL queries - Handling localization in SQL conversion ### Templates and Customization 📄 **Read:** [references/templates-and-customization.md](references/templates-and-customization.md) - Creating custom header templates - Custom component injection into templates - Styling with CSS classes and cssClass property - Theme Studio integration - Custom operator definitions - Handling actionBegin events for customization ### Advanced Features 📄 **Read:** [references/advanced-features.md](references/advanced-features.md) - Display modes (Horizontal and Vertical layouts) - Cloning rules and groups with cloneRule/cloneGroup - Locking rules and groups for read-only access - Separate connectors for visual distinction - Restricting group operations - RTL (Right-to-Left) support - State persistence with enablePersistence - Sort direction configuration - Summary view display - Accessibility and keyboard navigation ### API Reference 📄 **Read:** [references/api-reference.md](references/api-reference.md) - Complete properties list with types and defaults - All methods with parameters and return types - Event handlers and event arguments - Model interfaces (RuleModel, ColumnsModel, ShowButtonsModel) - Return type definitions and data structures - Property usage patterns ## Quick Start Example ```tsx import { ColumnsModel, QueryBuilderComponent, RuleModel } from '@syncfusion/ej2-react-querybuilder'; import React from 'react'; function App() { const columnData: ColumnsModel[] = [ { field: 'EmployeeID', label: 'Employee ID', type: 'number' }, { field: 'FirstName', label: 'First Name', type: 'string' }, { field: 'Title', label: 'Title', type: 'string' }, { field: 'HireDate', label: 'Hire Date', type: 'date', format: 'dd/MM/yyyy' }, { field: 'Country', label: 'Country', type: 'string' } ]; const initialRules: RuleModel = { condition: 'and', rules: [ { field: 'EmployeeID', label: 'Employee ID', operator: 'equal', type: 'number', value: 1001 } ] }; return ( <QueryBuilderComponent width="100%" columns={columnData} rule={initialRules} /> ); } export default App; ``` ## Common Patterns ### Pattern 1: Retrieving Filtered Results as SQL ```tsx let qryBldrObj: QueryBuilderComponent; function generateSQL() { const sqlQuery = qryBldrObj.getSqlFromRules(); console.log('Generated SQL:', sqlQuery); // Send to backend for execution } ``` ### Pattern 2: Programmatically Adding Rules ```tsx function addFilter() { qryBldrObj.addRules([ { field: 'Country', label: 'Country', operator: 'equal', type: 'string', value: 'USA' } ], 'group0'); } ``` ### Pattern 3: Converting SQL Back to Rules ```tsx function importFilter(sqlString: string) { qryBldrObj.setRulesFromSql(sqlString); } ``` ### Pattern 4: Displaying Summary View ```tsx <QueryBuilderComponent columns={columnData} summaryView={true} // Shows query summary at the bottom /> ``` ## Key Props Cheat Sheet | Prop | Type | Default | Purpose | |------|------|---------|---------| | `columns` | ColumnsModel[] | - | Defines available fields and operators | | `rule` | RuleModel | {} | Initial filter rules | | `dataSource` | Object[] \| DataManager | [] | Data for binding | | `displayMode` | 'Horizontal' \| 'Vertical' | 'Horizontal' | Layout orientation | | `allowDragAndDrop` | boolean | false | Enable drag-drop rule management | | `enablePersistence` | boolean | false | Save state to localStorage | | `enableRtl` | boolean | false | Right-to-left layout | | `allowValidation` | boolean | false | Validate rule conditions | | `summaryView` | boolean | false | Show filtered query summary | | `showButtons` | ShowButtonsModel | defaults | Control add/delete button visibility | | `maxGroupCount` | number | 5 | Maximum nested group depth | | `readonly` | boolean | false | Make component read-only | ## Common Use Cases ### Use Case 1: Advanced Search Filter Create a filter interface for users to build complex search queries with multiple conditions: 1. Define columns for searchable fields 2. Initialize with empty or default rules 3. Set `showButtons` to enable rule management 4. Retrieve SQL on form submission 5. Execute query on backend **Read:** [references/rules-and-filtering.md](references/rules-and-filtering.md) and [references/query-conversion.md](references/query-conversion.md) ### Use Case 2: Data-Driven Dashboard Build a dashboard where users filter data across multiple columns: 1. Bind DataManager with remote service 2. Configure columns based on data types 3. Enable drag-and-drop for better UX 4. Use getPredicate() to filter DataManager 5. Display filtered results dynamically **Read:** [references/data-binding.md](references/data-binding.md) and [references/rules-and-filtering.md](references/rules-and-filtering.md) ### Use Case 3: Query Template System Allow users to save and load filter templates: 1. Set `enablePersistence={true}` for automatic state saving 2. Or manually save `getRules()` to database 3. Load rules with `setRules()` when needed 4. Display saved templates in a dropdown **Read:** [references/advanced-features.md](references/advanced-features.md) ### Use Case 4: Report Builder Create a report filter UI with custom templates: 1. Design custom header template for branding 2. Use custom operators for domain-specific filtering 3. Enable validation with `allowValidation` 4. Display `summaryView` for clarity 5. Generate SQL for report execution **Read:** [references/templates-and-customization.md](references/templates-and-customization.md) and [references/advanced-features.md](references/advanced-features.md) ## Next Steps 1. **Getting Started:** Install the package and create your first Query Builder 2. **Define Columns:** Configure the fields users can filter on 3. **Bind Data:** Connect to local or remote data sources 4. **Build UI:** Add rules and groups with drag-and-drop support 5. **Generate Queries:** Convert rules to SQL or other formats 6. **Customize:** Apply themes, templates, and accessibility features --- **Need help?** Check the specific reference files above for detailed examples and implementation patterns.