syncfusion-vue-query-builder

name	syncfusion-vue-query-builder
description	Comprehensive guide to implementing Syncfusion Vue Query Builder component using Vue 3 Composition API. Use this skill when building advanced filter interfaces, creating complex data query systems, or implementing dynamic rule-based filtering in Vue 3 applications. Covers query builder configuration, SQL query conversion, drag-and-drop filtering, customization, and state management with Vue 3 reactive patterns.
metadata	{"author":"Syncfusion Inc","version":"34.1.29","category":"Forms"}

Implementing Syncfusion Vue Query Builder

A comprehensive guide for implementing and customizing the Syncfusion Vue Query Builder component using Vue 3 Composition API. 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
• Vue 3 Composition API: Reactive state management with ref(), computed(), and provide/inject

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Installation and package setup for Vue 3
• Basic component initialization with Composition API
• CSS imports and themes (Tailwind3, Bootstrap5.3, Material3)
• Creating your first Query Builder with ref() pattern
• Column definition basics with TypeScript
• Running the application with Vite

Columns and Operators

📄 Read: references/columns-and-operators.md

• Defining column schema with ColumnsModel interface
• Auto-generating columns from data sources
• Configuring labels and field mappings
• Supported operators by data type
• Setting step and format properties
• Column validation configuration with reactive validation

Data Binding

📄 Read: references/data-binding.md

• Binding local data arrays with reactive()
• Remote data with DataManager adapter
• ODataV4Adaptor integration in Vue 3
• Dynamic data updates with watch()
• Using DataManager with Query Builder
• Handling data source changes reactively

Rules and Filtering

📄 Read: references/rules-and-filtering.md

• Understanding rule structure (RuleModel)
• Creating rules programmatically with addRules()
• Creating groups with addGroups() methods
• Deleting rules and groups via template refs
• Managing nested rule hierarchies
• Drag-and-drop rule management
• Show buttons configuration

Query Conversion

📄 Read: 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

• Creating custom header templates with v-slot pattern
• Custom component injection into templates
• Styling with CSS classes and cssClass property
• Theme Studio integration (Tailwind3, Bootstrap5.3)
• Custom operator definitions
• Handling actionBegin events for customization

Advanced Features

📄 Read: 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

• 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 in Vue 3 context

Quick Start Example

<template>
  <div class="query-builder-container">
    <h1>Query Builder</h1>
    <ejs-querybuilder
      ref="qbRef"
      width="100%"
      :columns="columns"
      :rule="initialRules"
      @change="handleChange"
    />
    <div class="actions">
      <button @click="generateSQL" class="btn-primary">Generate SQL</button>
      <button @click="resetQuery" class="btn-secondary">Reset</button>
    </div>
    <div v-if="sqlQuery" class="result">
      <p><strong>SQL Query:</strong></p>
      <code>{{ sqlQuery }}</code>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, reactive } from 'vue';
import { QueryBuilderComponent } from '@syncfusion/ej2-vue-querybuilder';
import type { ColumnsModel, RuleModel } from '@syncfusion/ej2-vue-querybuilder';

// Template reference
const qbRef = ref<QueryBuilderComponent>();

// Columns definition
const columns: 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' }
];

// Initial rules
const initialRules: RuleModel = {
  condition: 'and',
  rules: [
    {
      field: 'EmployeeID',
      label: 'Employee ID',
      operator: 'equal',
      type: 'number',
      value: 1001
    }
  ]
};

// State
const sqlQuery = ref<string>('');

// Methods
const generateSQL = () => {
  if (qbRef.value) {
    sqlQuery.value = qbRef.value.getSqlFromRules() || '';
  }
};

const resetQuery = () => {
  if (qbRef.value) {
    qbRef.value.reset();
    sqlQuery.value = '';
  }
};

const handleChange = () => {
  console.log('Query changed');
};
</script>

<style>
.query-builder-container {
  padding: 20px;
  max-width: 800px;
  margin: 0 auto;
}

.actions {
  margin-top: 20px;
  display: flex;
  gap: 10px;
}

.btn-primary,
.btn-secondary {
  padding: 10px 20px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  font-size: 14px;
}

.btn-primary {
  background-color: #007bff;
  color: white;
}

.btn-secondary {
  background-color: #6c757d;
  color: white;
}

.result {
  margin-top: 20px;
  padding: 15px;
  background-color: #f8f9fa;
  border: 1px solid #dee2e6;
  border-radius: 4px;
}

code {
  background-color: #f3f4f6;
  padding: 10px;
  display: block;
  border-radius: 4px;
  font-family: 'Courier New', monospace;
  overflow-x: auto;
}
</style>

Common Patterns

Pattern 1: Retrieving Filtered Results as SQL

const qbRef = ref<QueryBuilderComponent>();

const generateSQL = () => {
  const sqlQuery = qbRef.value?.getSqlFromRules();
  console.log('Generated SQL:', sqlQuery);
  // Send to backend for execution
};

Pattern 2: Programmatically Adding Rules

const addFilter = () => {
  qbRef.value?.addRules([
    {
      field: 'Country',
      label: 'Country',
      operator: 'equal',
      type: 'string',
      value: 'USA'
    }
  ], 'group0');
};

Pattern 3: Converting SQL Back to Rules

const importFilter = (sqlString: string) => {
  qbRef.value?.setRulesFromSql(sqlString);
};

Pattern 4: Displaying Summary View with Reactive State

<template>
  <ejs-querybuilder
    :columns="columns"
    :summaryView="showSummary"
  />
  <button @click="showSummary = !showSummary">
    {{ showSummary ? 'Hide' : 'Show' }} Summary
  </button>
</template>

<script setup>
import { ref } from 'vue';

const showSummary = ref(false);
</script>

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 and 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 and 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

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 and 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.