Vue.js 3 Query Builder# Vue.js 3 Query Builder# Vue.js 3 Query Builder

A flexible and customizable query builder component for Vue.js 3, designed to work seamlessly with Vuetify 3. Create complex, nested policy rules and queries using a simple and intuitive UI.

Effortlessly build advanced filtering logic with support for grouping, multiple operators, and diverse field types. The component includes built-in validation to ensure all required fields (Entity/Field, Value) are filled before saving. Highly extensible, making it easy to tailor the user experience and appearance to your project's requirements. Ideal for dashboards, admin panels## Changelog

v1.9.0

• 📦 Fixed dist/style.css physically included in the package for full backward compatibility
• 🔧 Users can import CSS via either dist/style.css or dist/query-builder.css

v1.8.9olicy rule engines, and any application that needs advanced search or filtering capabilities.A flexible and customizable query builder component for Vue.js 3, designed to work seamlessly with Vuetify 3. Create complex, nested policy rules and queries using a simple and intuitive UI.A flexible and customizable query builder component for Vue.js 3, designed to work seamlessly with Vuetify. Create complex, nested queries using a simple and intuitive UI.

✨ FeaturesEffortlessly build advanced filtering logic with support for grouping, multiple operators, and diverse field types. The component includes built-in validation to ensure all required fields (Entity/Field, Value) are filled before saving. Highly extensible, making it easy to tailor the user experience and appearance to your project's requirements. Ideal for dashboards, admin panels, policy rule engines, and any application that needs advanced search or filtering capabilities.Effortlessly build advanced filtering logic with support for grouping, multiple operators, and diverse field types. The component is highly extensible, making it easy to tailor the user experience and appearance to your project’s requirements. With a focus on usability and performance, this query builder is ideal for dashboards, admin panels, and any application that needs advanced search or filtering capabilities.

• 🔧 Nested Groups — Create complex AND/OR logic with unlimited nesting

• ✅ Built-in Validation — Validates Entity (field) and Value are present before saving

• 🎨 Customizable Colors — Pass your own theme color via the color prop---

• 🧩 Custom Operators — Define your own operators (equal, contains, begins_with, etc.)

• 📦 Custom Fields — Pass any list of field names---

• 🔌 Vuetify 3 Integration — Built on Vuetify 3 components

• 📤 Exposed validate() Method — Programmatically validate the entire query tree via template ref## ✨ Features

---## Installation

Installation- 🔧 Nested Groups — Create complex AND/OR logic with unlimited nesting

Install the package via npm:- ✅ Built-in Validation — Validates Entity (field) and Value are present before savingInstall the package via npm:

```bash- 🎨 Customizable Colors — Pass your own theme color via the color prop

npm install vuejs3-vuetify-query-builder

- 🧩 **Custom Operators** — Define your own operators (`equal`, `contains`, `begins_with`, etc.)bash

---- 📦 Custom Fields — Pass any list of field namesnpm install @vuejs3/vuetify-query-builder

Basic Usage- 🔌 Vuetify 3 Integration — Built on Vuetify 3 components```

Import and register the component in your Vue 3 application.- 📤 Exposed validate() Method — Programmatically validate the entire query tree via template ref

CSS Import---

import 'vuejs3-vuetify-query-builder/dist/query-builder.css'

```## Basic Usage



### 1. Using the Options API## Installation



```vueImport and register the component in your Vue 3 application. Supports both the Options API and Composition API.

<template>

  <query-builderInstall the package via npm:

    v-model="filter"

    :filter-fields="filterFields"### 1. Using the Options API

    :filter-operators="filterOperators"

    :color="color"```bash

  />

</template>npm install vuejs3-vuetify-query-builder```vue



<script>```<template>

import QueryBuilder from 'vuejs3-vuetify-query-builder'

import 'vuejs3-vuetify-query-builder/dist/query-builder.css'  <query-builder v-model="filter" :filter-fields="filterFields" :color="color" />



export default {---</template>

  components: { QueryBuilder },

  data() {

    return {

      filter: {},## Basic Usage<script>

      filterFields: ['Entity Name', 'Severity', 'Host Name', 'Description', 'Tool Name'],

      filterOperators: [import QueryBuilder from '@vuejs3/vuetify-query-builder'

        { value: 'eq', text: 'equal', type: 'string' },

        { value: 'ne', text: 'not_equal', type: 'string' },Import and register the component in your Vue 3 application. Supports both the Options API and Composition API.import '@vue/vuetify-query-builder/dist/style.css'

        { value: 'contains', text: 'contains', type: 'string' },

        { value: 'begins_with', text: 'begins_with', type: 'string' },

        { value: 'ends_with', text: 'ends_with', type: 'string' }

      ],### 1. Using the Options APIexport default {

      color: '#1e3799'

    }  components: { QueryBuilder },

  }

}```vue  data() {

</script>

```<template>    return {



### 2. Using the Composition API  <query-builder      filter: {},



```vue    v-model="filter"      filterFields: ['id', 'name', 'date', 'gender'],

<template>

  <query-builder    :filter-fields="filterFields"      color: 'royalblue'

    ref="queryBuilderRef"

    v-model="query"    :filter-operators="filterOperators"    }

    :filter-fields="filterFields"

    :filter-operators="filterOperators"    :color="color"  }

    :color="color"

  />  />}

  <button @click="handleSave">Save Policy</button>

</template></template></script>



<script setup>```

import QueryBuilder from 'vuejs3-vuetify-query-builder'

import 'vuejs3-vuetify-query-builder/dist/query-builder.css'<script>

import { ref } from 'vue'

import QueryBuilder from 'vuejs3-vuetify-query-builder'### 2. Using the Composition API

const queryBuilderRef = ref(null)

const query = ref({})import 'vuejs3-vuetify-query-builder/dist/style.css'

const filterFields = ['Entity Name', 'Severity', 'Host Name', 'Description', 'Tool Name']

const filterOperators = [```vue

  { value: 'eq', text: 'equal', type: 'string' },

  { value: 'ne', text: 'not_equal', type: 'string' },export default {<template>

  { value: 'contains', text: 'contains', type: 'string' },

  { value: 'begins_with', text: 'begins_with', type: 'string' },  components: { QueryBuilder },  <query-builder v-model="query" :filter-fields="filterFields" :color="color" />

  { value: 'ends_with', text: 'ends_with', type: 'string' }

]  data() {</template>

const color = '#1e3799'

    return {

function handleSave() {

  const isValid = queryBuilderRef.value.validate()      filter: {},<script setup>

  if (isValid) {

    console.log('Query is valid:', query.value)      filterFields: ['Entity Name', 'Severity', 'Host Name', 'Description', 'Tool Name'],import QueryBuilder from '@vuejs3/vuetify-query-builder'

    // Save the policy rule...

  } else {      filterOperators: [import '@vue/vuetify-query-builder/dist/style.css'

    console.log('Validation failed — Entity/Value fields are missing.')

  }        { value: 'eq', text: 'equal', type: 'string' },import { ref } from 'vue'

}

</script>        { value: 'ne', text: 'not_equal', type: 'string' },

    { value: 'contains', text: 'contains', type: 'string' },const query = ref({})

    { value: 'begins_with', text: 'begins_with', type: 'string' },const filterFields = ['id', 'name', 'date', 'gender']

Props

    { value: 'ends_with', text: 'ends_with', type: 'string' }const color = 'royalblue'

| Prop | Type | Required | Default | Description |

| ----------------- | ----------------- | -------- | --------- | -------------------------------------------------- | ],

| modelValue | object / Query| Yes | {} | The current query object (for v-model binding). |

| filterFields | Array<string> | Yes | [] | List of fields available for filtering. | color: '#1e3799'```

| filterOperators | Array<Operator> | Yes | [] | List of operators available for filtering. |

| color | string | No | #1e3799 | Color theme for the group header border. | }

--- }---

Exposed Methods}

| Method | Returns | Description |## Props

| ------------ | --------- | -------------------------------------------------------------------------------------------------------- |

| validate() | boolean | Validates all rules in the query tree. Returns true if valid, false if any Entity or Value is empty. |```

Usage:| Prop | Type | Required | Default | Description |

const isValid = queryBuilderRef.value.validate()

```| `modelValue`   | `object` or `Query`         | Yes      | `{}`        | The current query object (for v-model binding).                    |



---```vue| `filterFields` | `Array<string>`             | Yes      | `[]`        | List of fields available for filtering.                            |



## Supported Operators<template>| `color`        | `string`                    | No       | primary     | Color theme for the component. Uses your project's primary color by default. |



| Value         | Text              | Type     | Description                     |  <query-builder

| ------------- | ----------------- | -------- | ------------------------------- |

| `eq`          | `equal` / `=`     | `string` | Equal to                        |    ref="queryBuilderRef"### Query Format

| `ne`          | `not_equal` / `!=`| `string` | Not equal to                    |

| `gt`          | `>`               | `string` | Greater than                    |    v-model="query"

| `lt`          | `<`               | `string` | Less than                       |

| `gte`         | `>=`              | `string` | Greater than or equal           |    :filter-fields="filterFields"The value bound to `v-model` should match this interface:

| `lte`         | `<=`              | `string` | Less than or equal              |

| `contains`    | `contains`        | `string` | Contains substring              |    :filter-operators="filterOperators"

| `begins_with` | `begins_with`     | `string` | Begins with                     |

| `ends_with`   | `ends_with`       | `string` | Ends with                       |    :color="color"```ts

| `regexp`      | `regexp`          | `string` | Regular expression match        |

| `not regexp`  | `not regexp`      | `string` | Not matching regex              |  />interface Query {

| `like`        | `like`            | `string` | SQL LIKE pattern                |

| `not like`    | `not like`        | `string` | SQL NOT LIKE pattern            |  <button @click="handleSave">Save Policy</button>  logicalOperator: 'AND' | 'OR'

| `exists`      | `exists`          | `none`   | Field exists (no value needed)  |

| `not exists`  | `not exists`      | `none`   | Field does not exist            |</template>  children: Array<Query | QueryRule>

| `is null`     | `is null`         | `none`   | Field is null                   |

| `not null`    | `not null`        | `none`   | Field is not null               |}

| `in`          | `in`              | `array`  | Value is in list                |

| `not in`      | `not in`          | `array`  | Value is not in list            |<script setup>



> **Operator `type`** determines the value input:import QueryBuilder from 'vuejs3-vuetify-query-builder'interface QueryRule {

> - `string` — Text field

> - `array` — Multi-value comboboximport 'vuejs3-vuetify-query-builder/dist/style.css'  rule?: string

> - `none` — No value input (e.g., `exists`, `is null`)

import { ref } from 'vue'  operator: string // e.g. '=', '!=', '>', etc.

---

  operand: string

## Query Format

const queryBuilderRef = ref(null)  value: Array<string | number> | string | number | null

The value bound to `v-model` follows this structure:

const query = ref({})}

```ts

interface Query {const filterFields = ['Entity Name', 'Severity', 'Host Name', 'Description', 'Tool Name']```

  logicalOperator: 'AND' | 'OR'

  children: Array<Child<Query | QueryRule>>const filterOperators = [

}

  { value: 'eq', text: 'equal', type: 'string' },---

interface QueryRule {

  rule?: string  { value: 'ne', text: 'not_equal', type: 'string' },

  operator: string   // e.g. 'eq', 'contains', 'begins_with'

  operand: string    // The field/entity name  { value: 'contains', text: 'contains', type: 'string' },## Example Query Object

  value: Array<string | number> | string | number | null

}  { value: 'begins_with', text: 'begins_with', type: 'string' },

{ value: 'ends_with', text: 'ends_with', type: 'string' }```json

]{

Example Query Object

const color = '#1e3799' "logicalOperator": "AND",

{  "children": [

  "logicalOperator": "AND",

  "children": [function handleSave() {    {

    {

      "type": "query-builder-rule",  const isValid = queryBuilderRef.value.validate()      "rule": "name",

      "query": {

        "rule": "Entity Name",  if (isValid) {      "operator": "=",

        "operator": "equal",

        "operand": "Entity Name",    console.log('Query is valid:', query.value)      "operand": "name",

        "value": "Server-01"

      }    // Save the policy rule...      "value": "John"

    },

    {  } else {    },

      "type": "query-builder-group",

      "query": {    console.log('Validation failed — Entity/Value fields are missing.')    {

        "logicalOperator": "OR",

        "children": [  }      "logicalOperator": "OR",

          {

            "type": "query-builder-rule",}      "children": [

            "query": {

              "rule": "Severity",</script>        {

              "operator": "equal",

              "operand": "Severity",```          "rule": "age",

              "value": "Critical"

            }          "operator": ">",

          },

          {---          "operand": "age",

            "type": "query-builder-rule",

            "query": {          "value": 30

              "rule": "Description",

              "operator": "contains",## Props        },

              "operand": "Description",

              "value": "timeout"        {

            }

          }| Prop              | Type              | Required | Default   | Description                                        |          "rule": "gender",

        ]

      }| ----------------- | ----------------- | -------- | --------- | -------------------------------------------------- |          "operator": "=",

    }

  ]| `modelValue`      | `object` / `Query`| Yes      | `{}`      | The current query object (for `v-model` binding).  |          "operand": "gender",

}

```| `filterFields`    | `Array<string>`   | Yes      | `[]`      | List of fields available for filtering.            |          "value": "male"



---| `filterOperators` | `Array<Operator>` | Yes      | `[]`      | List of operators available for filtering.         |        }



## Screenshot| `color`           | `string`          | No       | `#1e3799` | Color theme for the group header border.           |      ]



![image](https://github.com/user-attachments/assets/7f9bbb39-4887-48d2-ac27-8c1593157b44)    }



![Existing query object:](image.png)---  ]



---}



## Changelog## Exposed Methods```



### v1.8.9



- 🔧 Fixed CSS import path — use `dist/query-builder.css` instead of `dist/style.css`| Method       | Returns   | Description                                                                                              |---

- 📦 Added `style` field and export aliases in `package.json` for backward compatibility

| ------------ | --------- | -------------------------------------------------------------------------------------------------------- |

### v1.8.8

| `validate()` | `boolean` | Validates all rules in the query tree. Returns `true` if valid, `false` if any Entity or Value is empty. |## Screenshot

- ✅ Added **validation** for Entity (field) and Value — prevents saving incomplete policy rules

- 🎨 Updated **color theme** with customizable project colors

- 🧹 Cleaned up UI — group header (`#E8EBF6`), child wrap (white), delete button hover (red)

- 📤 Exposed `validate()` method via template ref for programmatic validationUsage:![image](https://github.com/user-attachments/assets/7f9bbb39-4887-48d2-ac27-8c1593157b44)

- ➕ Added support for `contains`, `begins_with`, `ends_with` operators

- 🗑️ Delete button shows red on hover for clear destructive action feedback



---```js![Existing query object:](image.png)



## Creditsconst isValid = queryBuilderRef.value.validate()



Developed and maintained by Harshal Birari```


---

---



## Supported Operators

---

| Value         | Text              | Type     | Description                     |

| ------------- | ----------------- | -------- | ------------------------------- |## Credits

| `eq`          | `equal` / `=`     | `string` | Equal to                        |

| `ne`          | `not_equal` / `!=`| `string` | Not equal to                    |Developed and maintained by Harshal Birari 
| `gt`          | `>`               | `string` | Greater than                    |
| `lt`          | `<`               | `string` | Less than                       |
| `gte`         | `>=`              | `string` | Greater than or equal           |
| `lte`         | `<=`              | `string` | Less than or equal              |
| `contains`    | `contains`        | `string` | Contains substring              |
| `begins_with` | `begins_with`     | `string` | Begins with                     |
| `ends_with`   | `ends_with`       | `string` | Ends with                       |
| `regexp`      | `regexp`          | `string` | Regular expression match        |
| `not regexp`  | `not regexp`      | `string` | Not matching regex              |
| `like`        | `like`            | `string` | SQL LIKE pattern                |
| `not like`    | `not like`        | `string` | SQL NOT LIKE pattern            |
| `exists`      | `exists`          | `none`   | Field exists (no value needed)  |
| `not exists`  | `not exists`      | `none`   | Field does not exist            |
| `is null`     | `is null`         | `none`   | Field is null                   |
| `not null`    | `not null`        | `none`   | Field is not null               |
| `in`          | `in`              | `array`  | Value is in list                |
| `not in`      | `not in`          | `array`  | Value is not in list            |

> **Operator `type`** determines the value input:
> - `string` → Text field
> - `array` → Multi-value combobox
> - `none` → No value input (e.g., `exists`, `is null`)

---

## Query Format

The value bound to `v-model` follows this structure:

```ts
interface Query {
  logicalOperator: 'AND' | 'OR'
  children: Array<Child<Query | QueryRule>>
}

interface QueryRule {
  rule?: string
  operator: string   // e.g. 'eq', 'contains', 'begins_with'
  operand: string    // The field/entity name
  value: Array<string | number> | string | number | null
}

Example Query Object

{
  "logicalOperator": "AND",
  "children": [
    {
      "type": "query-builder-rule",
      "query": {
        "rule": "Entity Name",
        "operator": "equal",
        "operand": "Entity Name",
        "value": "Server-01"
      }
    },
    {
      "type": "query-builder-group",
      "query": {
        "logicalOperator": "OR",
        "children": [
          {
            "type": "query-builder-rule",
            "query": {
              "rule": "Severity",
              "operator": "equal",
              "operand": "Severity",
              "value": "Critical"
            }
          },
          {
            "type": "query-builder-rule",
            "query": {
              "rule": "Description",
              "operator": "contains",
              "operand": "Description",
              "value": "timeout"
            }
          }
        ]
      }
    }
  ]
}

Screenshot

Changelog

v1.8.7

• ✅ Added validation for Entity (field) and Value — prevents saving incomplete policy rules
• 🎨 Updated color theme with customizable project colors
• 🧹 Cleaned up UI — group header (#E8EBF6), child wrap (white), delete button hover (red)
• 📤 Exposed validate() method via template ref for programmatic validation
• ➕ Added support for contains, begins_with, ends_with operators
• 🗑️ Delete button shows red on hover for clear destructive action feedback

Credits

Developed and maintained by Harshal Birari