Query builder
Builds nested filter conditions from fields, operators, and values.
Preview
(Name contains "Drive")
In action
(Name contains "Drive")
When to use
Use it for
- User-defined filters and conditional rule sets.
Not for
- Executing SQL or trusting the summary as a database query.
Install
Three ways in. They share one source, so the pixels match whichever you pick.
1. Import the package
npm install @noorddev/vlak-react
// once, next to your app's root
import "@noorddev/vlak-react/css";
import { QueryBuilder } from "@noorddev/vlak-react";Precompiled React and one stylesheet. No compiler to configure. Per-component imports work too: @noorddev/vlak-react/components/query-builder.
2. Vendor the source
npx @noorddev/vlak-cli add query-builder
The StyleX leaf lands in components/vlak/ with its dependencies, for your own compiler to own. See StyleX.
3. Through shadcn
npx shadcn add https://vlak.dev/r/query-builder.json
The same registry item, installed by shadcn's CLI.
CSS only
<link rel="stylesheet" href="node_modules/@noorddev/vlak/css/vlak.css" />
No React. Link vlak.css and use the markup and classes below.
React
import { QueryBuilder } from "@noorddev/vlak-react";
<QueryBuilder fields={[{ id: "name", label: "Name" }, { id: "range", label: "Range", type: "number" }]} defaultValue={{ id: "root", combinator: "and", rules: [{ id: "rule", field: "name", operator: "contains", value: "Drive" }] }} />Props
describeQuery (function)
Human-readable summary only. This is not SQL and never executes a query.
QueryBuilder
A structured filter expression with nested groups and native field editors.
| Prop | Type | Default | Description |
|---|---|---|---|
fieldsrequired | QueryField[] | ||
value | QueryGroup | ||
defaultValue | QueryGroup | ||
onValueChange | (query: QueryGroup) => void | ||
label | string | "Filter conditions" | |
maxDepth | number | 3 | Maximum group nesting, capped at eight. |
Also accepts Omit<HTMLAttributes<HTMLDivElement>, "defaultValue">.
Keyboard
| Keys | Does |
|---|---|
| Tab, Enter, Space, native select keys | Native fields handle entry and selection; buttons add or remove rules/groups. |
Accessibility
- Fieldsets name nested groups. Every editor has a label and a human-readable expression summary is available.
Markup
<div class="rs-query-builder"><fieldset class="rs-query-builder-group"><legend class="rs-query-builder-legend">Filter conditions</legend><p class="rs-query-builder-summary">Name contains "Drive"</p></fieldset></div>