The QueryBuilder is a powerful Syncfusion component for building dynamic, complex queries with a visual UI. This skill provides comprehensive guidance for implementing, configuring, and customizing the QueryBuilder in TypeScript applications.
When to Use This Skill
Use this skill when you need to:
- Create interactive query builders for filtering data visually
- Define column schemas with types, operators, and validation
- Bind data from local sources or remote APIs
- Manage rules and groups with AND/OR logic
- Add drag-drop functionality for moving and cloning rules
- Customize templates for fields, operators, and values
- Export/import queries as JSON or SQL
- Ensure accessibility with keyboard navigation and ARIA
- Handle complex filtering scenarios in your TypeScript applications
Control Overview
QueryBuilder is an advanced UI component that enables users to build complex filter conditions without writing code. It supports:
- Multiple data types (string, number, date, boolean)
- Various operators (equals, contains, between, etc.)
- Rule grouping with AND/OR conditions
- Nested group hierarchies
- Custom templates for UI customization
- Drag-drop interactions (rearrange, clone, lock rules)
- JSON import/export and SQL generation
- RTL support and full keyboard accessibility
- WCAG 2.1 AA compliance
Documentation and Navigation Guide
Getting Started
📄 Read: references/getting-started.md
- Installation and npm package setup
- Syncfusion dependencies configuration
- CSS imports and theme setup
- Basic QueryBuilder initialization
- Column definitions with types
- Running your first QueryBuilder application
Columns and Schema Definition
📄 Read: references/columns-definition.md
- Column definitions and schema structure
- Auto-generation of columns from data
- Field mapping and labels
- Supported data types (string, number, date, boolean)
- Operators for each data type
- Step and format properties for numbers/dates
- Custom column configuration patterns
Data Binding
📄 Read: references/data-binding.md
- Local data binding with JavaScript arrays
- Remote data binding with DataManager
- DataSource assignment patterns
- RuleModel structure for predefined queries
- Binding with initial rules
- Dynamic data updates and refresh
- DataManager configuration
Rules and Groups Management
📄 Read: references/rules-and-groups.md
- Rule model structure (condition, rules, field, operator, value)
- Creating single filter rules
- Grouping rules with AND/OR logic
- Adding and deleting rules programmatically
- Adding and deleting groups
- Rule validation and constraints
- Nested group hierarchies
Filtering and Search Operations
📄 Read: references/filtering-search.md
- Filtering conditions creation and deletion
- Query execution methods
- Custom filter condition patterns
- Search functionality within conditions
- ShowButtons configuration (rule delete, group insert/delete)
- UI-based and programmatic filtering
- Event handling for filter changes
Templates and Customization
📄 Read: references/templates-customization.md
- Value template customization
- Operator template customization
- Field template customization
- Custom HTML template creation
- Template rendering and binding
- CSS class customization
- Dynamic template rendering patterns
Drag-Drop and Rule Interaction
📄 Read: references/drag-drop-clone-lock.md
- Drag and drop functionality for rules
- Cloning rules within groups
- Locking rules to prevent modification
- Separator and connector behavior
- Moving rules between groups
- Drag-drop event handling
- Visual feedback and styling
Import/Export and Persistence
📄 Read: references/import-export.md
- Exporting rules to JSON format
- Importing rules from JSON
- SQL query generation
- JSON serialization patterns
- Format conversions (rules to SQL/JSON)
- Data persistence strategies
- State management
Accessibility and RTL
📄 Read: references/accessibility-rtl.md
- WCAG 2.1 AA compliance standards
- Keyboard navigation patterns
- ARIA attributes and labels
- Screen reader support
- RTL (Right-to-Left) language support
- Focus management and indicators
- Localization and internationalization
Advanced Features and Troubleshooting
📄 Read: references/advanced-features.md
- Global and local configuration options
- Model binding patterns
- Advanced validation strategies
- Performance optimization techniques
- Event handling and callbacks
- State persistence patterns
- Common issues and troubleshooting
- Best practices for complex scenarios
Quick Start Example
Here's a minimal example to get started with QueryBuilder:
import { QueryBuilder, ColumnsModel, RuleModel } from '@syncfusion/ej2-querybuilder';
// Define your data
const employeeData = [
{
EmployeeID: 1,
FirstName: 'Nancy',
Title: 'Sales Representative',
HireDate: '22/07/2001',
City: 'Seattle',
Country: 'USA'
},
{
EmployeeID: 2,
FirstName: 'Andrew',
Title: 'Vice President',
HireDate: '21/04/2003',
City: 'Tacoma',
Country: 'USA'
}
];
// Define columns matching your data
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: 'City', label: 'City', type: 'string' },
{ field: 'Country', label: 'Country', type: 'string' }
];
// Optional: Define initial rules
const initialRules: RuleModel = {
condition: 'and',
rules: [
{
label: 'Employee ID',
field: 'EmployeeID',
type: 'number',
operator: 'equal',
value: 1
},
{
label: 'Title',
field: 'Title',
type: 'string',
operator: 'startswith',
value: 'Sales'
}
]
};
// Create QueryBuilder instance
const queryBuilder = new QueryBuilder({
width: '100%',
dataSource: employeeData,
columns: columnData,
rule: initialRules
});
// Render to DOM
queryBuilder.appendTo('#querybuilder');
Common Patterns
Pattern 1: Basic Filter with Single Rule
For simple filtering scenarios, use a single rule without groups:
const rule: RuleModel = {
condition: 'and',
rules: [{
field: 'FirstName',
type: 'string',
operator: 'startswith',
value: 'A'
}]
};
Pattern 2: AND/OR Logic with Groups
For complex filters combining multiple conditions:
const rule: RuleModel = {
condition: 'and',
rules: [
{ field: 'City', operator: 'equal', value: 'Seattle' },
{
condition: 'or',
rules: [
{ field: 'Title', operator: 'contains', value: 'Sales' },
{ field: 'Title', operator: 'contains', value: 'Manager' }
]
}
]
};
Pattern 3: Dynamic Rule Addition
Add rules programmatically in response to user actions:
const newRule = [{
field: 'Country',
operator: 'equal',
value: 'USA'
}];
queryBuilder.addRules(newRule, 'group0');
Pattern 4: Export to JSON for Storage
Save the current query state for persistence:
const rules = queryBuilder.getRules();
const jsonQuery = JSON.stringify(rules);
// Store in database or local storage
Key Concepts
- RuleModel: Represents a single filter condition with field, operator, and value
- Condition: Logical operator (AND/OR) for combining multiple rules
- GroupModel: Container for rules with AND/OR conditions
- Operators: Comparison methods (equal, contains, between, etc.)
- Data Types: Supported column types (string, number, date, boolean)
- Templates: Custom UI elements for fields, operators, and values
- State: Current configuration of rules and groups
Common Use Cases
- Advanced Search Filter - Let users build complex queries for data search
- Report Generation - Create dynamic filters for report parameters
- Data Export - Filter data before export with visual UI
- Log Analysis - Build complex queries to analyze system logs
- Customer Segmentation - Filter customers based on multiple criteria
- Permission Rules - Define access rules with complex conditions
- Notification Rules - Create dynamic alert conditions
- ETL Workflows - Filter source data before transformation
Need help with a specific feature? Check the reference files above for detailed guidance on columns, data binding, templates, and more!