Query Builder V2

A modern, framework-agnostic, and customizable query builder web component.

Features

- 🚀 Global & Framework Agnostic: Works everywhere (Vanilla JS, React, Vue, Angular).
- 📦 Zero Dependencies: Built with standard Web Components.
- 🎨 Modern Design: Clean UI with CSS Variables for easy customization.
- ⚡ Lightweight: Small bundle size.
- 🛡️ TypeScript: Written in TypeScript for stability.
- 🔍 Live Search: Async backend search with debouncing, caching, and hybrid modes.

Installation

$3

Simply include the script from a CDN (once published) or your local build:

``html







`

$3

Import the component to register it, then use it as a custom element.

`jsx
import React, { useEffect, useRef } from 'react';
import 'path/to/abt-query-builder.es.js'; // Registers

function App() {
const qbRef = useRef(null);

useEffect(() => {
if (qbRef.current) {
qbRef.current.fields = [
{ id: 'name', label: 'Name', type: 'string' }
];

const handleChange = (e) => {
console.log(e.detail);
};

qbRef.current.addEventListener('change', handleChange);

return () => {
qbRef.current?.removeEventListener('change', handleChange);
};
}
}, []);

return (



);
}
`

$3

`html



`

$3

1. Allow custom elements in your module:

`typescript
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';

@NgModule({
declarations: [AppComponent],
imports: [BrowserModule],
schemas: [CUSTOM_ELEMENTS_SCHEMA], // Important!
bootstrap: [AppComponent]
})
export class AppModule { }
`

2. Import the script in main.ts or angular.json.

3. Use in template:

`html

`

Supported Operators

The component supports various operators based on the field type:

- String: equal, not_equal, contains, not_contains, starts_with, ends_with, is_empty, is_not_empty, in_array, not_in_array
- Number: equal, not_equal, greater, less, between, is_empty, is_not_empty, in_array, not_in_array
- Date: equal, not_equal, greater, less, between, is_empty, is_not_empty, in_array, not_in_array
- Select: equal, not_equal, in_array, not_in_array, is_empty, is_not_empty
- Boolean: equal

$3

- Between: Displays two input fields ("From" and "To").
- In List / Not In List: Enables multi-value selection (Tags).

Multi-Value Support

When using in_array ("In List") or not_in_array ("Not In List") operators:

- Select Fields: You can select multiple options from the dropdown.
- Text/Number/Date Fields: Type a value (or pick a date) and press Enter to add it as a tag.

Live Search (Async Data)

For large datasets, you can configure select fields to fetch options dynamically from a backend API instead of loading all data upfront.

$3

`javascript
qb.fields = [
{
id: 'product',
label: 'Product',
type: 'select',
search: {
onSearch: async (term, fieldId) => {
const res = await fetch(/api/products?q=${term});
return res.json(); // { key: label, key2: label2, ... }
},
minChars: 2, // Minimum characters before search (default: 2)
debounceMs: 300 // Debounce delay in ms (default: 300)
}
}
];
`

$3

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| onSearch | (term: string, fieldId: string) => Promise> | required | Async callback to fetch options |
| onResolveLabel | (key: string, fieldId: string) => Promise | - | Resolve label for saved values |
| mode | 'local' \| 'remote' \| 'hybrid' | 'remote' | Search strategy |
| minChars | number | 2 | Min characters before triggering search |
| debounceMs | number | 300 | Debounce delay in milliseconds |
| cache | boolean \| number | true | Cache results (true = forever, number = TTL in ms) |
| hybridAlwaysFetch | boolean | false | Always fetch backend in hybrid mode, even if local results exist |
| hybridFetchThreshold | number | 1 | Minimum local results needed to skip backend fetch |
| placeholder | string | 'Type to search...' | Input placeholder |
| loadingText | string | 'Searching...' | Text shown while loading |
| noResultsText | string | 'No results found' | Text shown when no results |

$3

- remote: Always fetch from backend
- local: Only search in pre-loaded values (no API calls)
- hybrid: Search local values first, fallback to backend based on config

$3

Results are always sorted by best match (exact matches first, then partial matches).

| Config | Behavior |
|--------|----------|
| Default | Uses local results if any exist, otherwise fetches backend |
| hybridAlwaysFetch: true | Always fetches backend and merges with local |
| hybridFetchThreshold: 5 | Fetches backend if fewer than 5 local results |

$3

Pre-load popular items and fetch rest from backend:

`javascript
qb.fields = [
{
id: 'product',
label: 'Product',
type: 'select',
values: { 'popular1': 'Popular Item 1', 'popular2': 'Popular Item 2' },
search: {
onSearch: async (term, fieldId) => fetchProducts(term),
onResolveLabel: async (key, fieldId) => fetchProductLabel(key),
mode: 'hybrid',
hybridAlwaysFetch: true, // Always merge with backend results
cache: true
}
}
];
`

$3

When loading saved rules with setRules(), use onResolveLabel to fetch labels for stored keys:

`javascript
search: {
onSearch: async (term) => { / ... / },
onResolveLabel: async (key, fieldId) => {
const product = await fetch(/api/products/${key});
return product.name; // Returns the label for the key
}
}
`

Load Fields from API

For API-driven field configuration, use loadFieldsFromAPI() to fetch and auto-wire fields:

`javascript
// Load fields from API endpoint
await qb.loadFieldsFromAPI('/api/query-builder/fields');
`

$3

`json
[
{ "id": "name", "label": "Customer Name", "type": "string" },
{
"id": "status",
"label": "Status",
"type": "select",
"values": { "active": "Active", "inactive": "Inactive" }
},
{
"id": "category",
"label": "Category",
"type": "select",
"valuesEndpoint": "/api/categories"
},
{
"id": "product",
"label": "Product",
"type": "select",
"search": {
"endpoint": "/api/products/search",
"mode": "hybrid",
"minChars": 2
}
}
]
`

$3

| Property | Description |
|----------|-------------|
| values | Static inline values for small lists |
| valuesEndpoint | URL to fetch values once on load (for medium lists) |
| search.endpoint | URL for live search (appends ?q=term&field=id) |
| search.resolveLabelEndpoint | URL to resolve single value labels |

$3

Transform non-standard API responses:

`javascript
await qb.loadFieldsFromAPI('/api/columns', {
baseUrl: 'https://api.example.com',
mapper: (col) => ({
id: col.column_name,
label: col.display_name,
type: col.data_type === 'varchar' ? 'string' : col.data_type,
values: col.options
})
});
`

Custom Output Serialization

By default, the component outputs a specific JSON structure. You can customize this by setting the serializer property.

`javascript
const qb = document.getElementById('qb');

qb.serializer = (group) => {
// Transform the internal group structure to your desired format
// 'group' contains { id, condition, rules: [] }

// Example transformation
return {
logic: group.condition,
filters: group.rules.map(rule => {
if ('condition' in rule) {
// It's a nested group, handle recursively if needed
return qb.serializer(rule);
}
// It's a rule
return {
field: rule.field,
op: rule.operator,
val: rule.value
};
})
};
};
`

Custom Input Parsing (Import)

To load data from a custom structure back into the query builder, define a parser function and use the setRules method.

`javascript
const qb = document.getElementById('qb');

qb.parser = (data) => {
// Transform your custom data structure back to the internal format
// Internal format: { id, condition, rules: [] }

// Example transformation (simplified)
const transform = (node) => {
if (node.filters) {
return {
id: Math.random().toString(36).substr(2, 9),
condition: node.logic,
rules: node.filters.map(transform)
};
}
return {
id: Math.random().toString(36).substr(2, 9),
field: node.field,
operator: node.op,
value: node.val
};
};

return transform(data);
};

// Load data
const myData = { logic: 'AND', filters: [...] };
qb.setRules(myData);
`

Customization

You can customize the appearance using CSS variables:

`css
query-builder {
--qb-primary-color: #6366f1;
--qb-danger-color: #ef4444;
--qb-radius: 8px;
--qb-font-family: 'Inter', sans-serif;
}
`

Development

1. Install dependencies:
`bash
npm install
`

2. Start dev server:
`bash
npm run dev
`

3. Build for production:
`bash
npm run build
`

Publishing to NPM

1. Login to NPM:
`bash
npm login
`
2. Build the project:
`bash
npm run build
`
3. Publish:
`bash
npm publish --access public
`

Using via CDN

Once published to NPM, you can use the component directly in the browser via a CDN like unpkg or jsdelivr.

Using unpkg:
`html

`

Using jsdelivr:
`html

`

Example Usage:
`html












``