Vue 3 QueryBuilder

A powerful and flexible query builder component for Vue 3 with Element Plus.

Installation

``bash
npm install @mvtcode/vue3-querybuilder
`

Repository

`bash
git clone git@github.com:mvtcode/vue3-querybuilder.git
`

Usage

`vue



`

Enums

$3

`typescript
enum FilterType {
STRING = 'string',
NUMBER = 'number',
BOOLEAN = 'boolean',
DATE = 'date',
}
`

$3

`typescript
enum Operator {
EQUAL = 'equal',
NOT_EQUAL = 'not_equal',
CONTAINS = 'contains',
NOT_CONTAINS = 'not_contains',
BEGINS_WITH = 'begins_with',
ENDS_WITH = 'ends_with',
GREATER = 'greater',
GREATER_OR_EQUAL = 'greater_or_equal',
LESS = 'less',
LESS_OR_EQUAL = 'less_or_equal',
IN = 'in',
NOT_IN = 'not_in',
BETWEEN = 'between',
NOT_BETWEEN = 'not_between',
IS_EMPTY = 'is_empty',
IS_NOT_EMPTY = 'is_not_empty',
}
`

Props

| Prop | Type | Default | Description |
| ---------- | --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| modelValue | QueryBuilderRule \| QueryBuilderGroup | - | The current query value |
| filters | Filter[] | [] | Array of available filters |
| maxDepth | number | 0 | Maximum depth of nested groups. Set to 0 for unlimited depth, 1 to disable nested groups, or any positive number to limit the nesting level |
| language | string | 'vi' | Language for the component UI (supports 'en' and 'vi') |

Events

| Event | Parameters | Description |
| ----------------- | ------------------------------------------------ | ------------------------------------ |
| update:modelValue | (value: QueryBuilderRule \| QueryBuilderGroup) | Emitted when the query value changes |

Types

`typescript
interface Filter {
field: string
label: string
type: 'string' | 'number' | 'boolean' | 'date'
operators: string[]
}

interface QueryBuilderRule {
type: 'rule'
field: string
operator: string
value: any
}

interface QueryBuilderGroup {
type: 'group'
condition: 'and' | 'or'
rules: (QueryBuilderRule | QueryBuilderGroup)[]
}
`

Filter Configuration

Each filter can be configured with the following properties:

`typescript
interface Filter {
field: string // Field name
label: string // Display label
type: 'string' | 'number' | 'boolean' | 'date' // Data type
operators: string[] // Allowed operators
input?: string // Input type ('select', 'radio', 'date', etc.)
values?: Array<{
// Values for select/radio
value: string
text: string
}>
validation?: {
// Validation rules
format?: string // Format for date (YYYY-MM-DD)
min?: number // Minimum value for number
max?: number // Maximum value for number
step?: number // Step for number
}
}
`

Filter Types

$3

`typescript
{
field: 'name',
label: 'Name',
type: FilterType.STRING,
operators: [
Operator.EQUAL,
Operator.NOT_EQUAL,
Operator.CONTAINS,
Operator.NOT_CONTAINS,
Operator.BEGINS_WITH,
Operator.NOT_BEGINS_WITH,
Operator.ENDS_WITH,
Operator.NOT_ENDS_WITH,
Operator.IS_EMPTY,
Operator.IS_NOT_EMPTY,
],
}
`

$3

`typescript
{
field: 'email',
label: 'Email',
type: FilterType.EMAIL,
operators: [Operator.EQUAL, Operator.NOT_EQUAL, Operator.CONTAINS, Operator.NOT_CONTAINS],
input: 'email',
}
`

$3

`typescript
{
field: 'age',
label: 'Age',
type: FilterType.INTEGER,
validation: {
min: 0,
max: 100,
},
operators: [
Operator.EQUAL,
Operator.NOT_EQUAL,
Operator.GREATER,
Operator.GREATER_OR_EQUAL,
Operator.LESS,
Operator.LESS_OR_EQUAL,
Operator.BETWEEN,
Operator.NOT_BETWEEN,
],
}
`

$3

`typescript
{
field: 'birthdate',
label: 'Birth Date',
type: FilterType.DATE,
input: 'date',
validation: {
format: 'YYYY-MM-DD',
},
operators: [
Operator.EQUAL,
Operator.NOT_EQUAL,
Operator.GREATER,
Operator.GREATER_OR_EQUAL,
Operator.LESS,
Operator.LESS_OR_EQUAL,
Operator.BETWEEN,
Operator.NOT_BETWEEN,
],
}
`

$3

`typescript
{
field: 'active',
label: 'Active',
type: FilterType.BOOLEAN,
input: 'checkbox',
}
`

$3

`typescript
{
field: 'status',
label: 'Status',
type: FilterType.STRING,
input: 'select',
value: 'pending', // Giá trị mặc định
operators: [Operator.EQUAL, Operator.NOT_EQUAL, Operator.IN, Operator.NOT_IN],
}
`

Operators

Component supports the following operators:

- equal: Equal (=)
- not_equal: Not Equal (≠)
- contains: Contains (⊃)
- not_contains: Not Contains (⊅)
- begins_with: Begins With
- ends_with: Ends With
- greater: Greater Than (>)
- greater_or_equal: Greater Than or Equal (≥)
- less: Less Than (<)
- less_or_equal: Less Than or Equal (≤)
- in: In List
- not_in: Not In List
- between: Between
- not_between: Not Between
- is_empty: Is Empty
- is_not_empty: Is Not Empty

Query Result

The result is returned as an object with the following structure:

`typescript
{
type: 'group',
condition: 'and' | 'or',
rules: [
{
type: 'rule',
field: string,
operator: string,
value: any
},
// or another group
{
type: 'group',
condition: 'and' | 'or',
rules: []
}
]
}
`

Query Conversion

$3

`typescript
import { toSQL } from '@mvtcode/vue3-querybuilder'

const rules = {
type: 'group',
condition: 'and',
rules: [
{
type: 'rule',
field: 'name',
operator: Operator.EQUAL,
value: 'John',
},
{
type: 'rule',
field: 'age',
operator: Operator.GREATER_OR_EQUAL,
value: 18,
},
],
}

const sqlWhere = toSQL(rules)
// Output: name = 'John' AND age >= 18
`

$3

`typescript
import { toMongo } from '@mvtcode/vue3-querybuilder'

const rules = {
type: 'group',
condition: 'and',
rules: [
{
type: 'rule',
field: 'name',
operator: Operator.EQUAL,
value: 'John',
},
{
type: 'rule',
field: 'age',
operator: Operator.GREATER_OR_EQUAL,
value: 18,
},
],
}

const mongoQuery = toMongo(rules)
// Output: {
// $and: [
// { name: { $eq: 'John' } },
// { age: { $gte: 18 } }
// ]
// }
`

$3

`typescript
import { fromSQL } from '@mvtcode/vue3-querybuilder'

const rules = fromSQL("name = 'John' AND age >= 18")
// Output: {
// type: 'group',
// condition: 'and',
// rules: [
// {
// type: 'rule',
// field: 'name',
// operator: Operator.EQUAL,
// value: 'John'
// },
// {
// type: 'rule',
// field: 'age',
// operator: Operator.GREATER_OR_EQUAL,
// value: 18
// }
// ]
// }
`

$3

`typescript
import { fromMongo } from '@mvtcode/vue3-querybuilder'

const rules = fromMongo({
$and: [{ name: { $eq: 'John' } }, { age: { $gte: 18 } }],
})
// Output: {
// type: 'group',
// condition: 'and',
// rules: [
// {
// type: 'rule',
// field: 'name',
// operator: Operator.EQUAL,
// value: 'John'
// },
// {
// type: 'rule',
// field: 'age',
// operator: Operator.GREATER_OR_EQUAL,
// value: 18
// }
// ]
// }
`

$3

| QueryBuilder Operator | SQL Operator | MongoDB Operator |
| --------------------- | ------------ | ---------------- |
| EQUAL | = | $eq |
| NOT_EQUAL | != | $ne |
| CONTAINS | LIKE | $regex |
| NOT_CONTAINS | NOT LIKE | $not |
| BEGINS_WITH | LIKE | $regex |
| ENDS_WITH | LIKE | $regex |
| GREATER | > | $gt |
| GREATER_OR_EQUAL | >= | $gte |
| LESS | < | $lt |
| LESS_OR_EQUAL | <= | $lte |
| IN | IN | $in |
| NOT_IN | NOT IN | $nin |
| BETWEEN | BETWEEN | $and |
| NOT_BETWEEN | NOT BETWEEN | $nor |
| IS_EMPTY | IS NULL | $exists: false |
| IS_NOT_EMPTY | IS NOT NULL | $exists: true |

Tính năng mới và cải tiến

$3

Component cung cấp dynamic slots cho mỗi field với các props mở rộng:

`vue

`

$3

- FilterType.EMAIL: Tự động validation email
- FilterType.INTEGER: Hỗ trợ validation min/max và BETWEEN operators
- FilterType.DATE: Hỗ trợ date picker và date range
- FilterType.BOOLEAN: Hỗ trợ checkbox input
- FilterType.STRING: Hỗ trợ tất cả string operators

$3

- BETWEEN/NOT_BETWEEN: Tự động chuyển đổi input thành range
- IN/NOT_IN: Tự động enable multiple selection
- IS_EMPTY/IS_NOT_EMPTY: Không cần input value
- BEGINS_WITH/ENDS_WITH: Hỗ trợ pattern matching

$3

Tất cả slots đều nhận widthValueInput prop để control width của input:

`vue

`

$3

| Name | Type | Description |
| ----------------- | ------------------ | ---------------------------------------------- |
| rule | QueryBuilderRule | Toàn bộ rule object với field, operator, value |
| operator | string | Current operator của rule |
| value | any | Current value của rule (alias cho rule.value) |
| isBetween | boolean | Có phải BETWEEN/NOT_BETWEEN operator không |
| widthValueInput | number | Width được tính toán cho value input |
| index | number | Index của rule trong group |

$3

Component tự động tạo slots dựa trên field names trong filters configuration. Ví dụ, nếu bạn có filter với field: 'name', bạn có thể sử dụng #name slot để customize input.

Mỗi slot nhận các props:

- rule: Toàn bộ rule object với field, operator, value
- operator: Current operator được chọn cho rule
- value: Current value của rule (alias cho rule.value)
- isBetween: Boolean flag chỉ ra operator có phải BETWEEN hoặc NOT_BETWEEN không
- widthValueInput: Width được tính toán cho value input
- index: Index của rule trong group

Khi isBetween là true, rule.value sẽ là array với 2 elements cho range values.

Kết quả Query từ Demo

Với cấu hình filters trong ví dụ, bạn có thể tạo ra các query phức tạp như:

`json
{
"condition": "AND",
"rules": [
{
"id": "uuid-1",
"field": "name",
"operator": "contains",
"value": "John"
},
{
"id": "uuid-2",
"field": "age",
"operator": "between",
"value": [18, 65]
},
{
"id": "uuid-3",
"field": "birthdate",
"operator": "greater",
"value": "1990-01-01"
},
{
"id": "uuid-4",
"field": "active",
"operator": "equal",
"value": true
},
{
"id": "uuid-5",
"field": "status",
"operator": "in",
"value": ["pending", "completed"]
}
]
}
`

Query này sẽ được convert thành:

SQL:

`sql
name LIKE '%John%'
AND age BETWEEN 18 AND 65
AND birthdate > '1990-01-01'
AND active = true
AND status IN ('pending', 'completed')
`

MongoDB:

`javascript
{
$and: [
{ name: { $regex: 'John', $options: 'i' } },
{ age: { $gte: 18, $lte: 65 } },
{ birthdate: { $gt: '1990-01-01' } },
{ active: { $eq: true } },
{ status: { $in: ['pending', 'completed'] } },
]
}
`

Development

`sh


Install dependencies

npm install

Run development server

npm run dev

Build for production

npm run build

Run unit tests

npm run test:unit

Lint and fix files

npm run lint
`

Examples

$3

Đây là ví dụ đầy đủ từ file App.vue với tất cả các loại filter và custom slots:

`vue



`

$3

`vue



`

$3

- maxDepth={0}: Unlimited nesting (default)
- maxDepth={1}: Disable nested groups completely
- maxDepth={n}`: Limit nesting to n levels (where n is a positive number)

License

MIT

Screenshot

!Vue 3 QueryBuilder Screenshot

Author

Mạc Tân (Tanmv)

Email: tanmv@mpos.vn

FB: Mạc Tân

Telegram: @tanmac

Skype: trai_12a1