Query builder

A React component in Beamline's Data & tables category.

Conditions people build by hand to pick out records: each rule is a field, an operator that fits the field (contains, between, in the last N days, is any of) and a value in the right control; rules join with and or or, groups nest them, the joining word toggles in place, an unfinished rule says so instead of counting, the query reads back as a sentence, and the number of matches rolls as it changes.

Use it for

Segments, audiences and saved views defined by several conditions with and/or: customers on Business with more than 10 seats who signed up this quarter.
Automation and alert rules (when these conditions hold, do this), with the matching count as feedback.

Not for

A few quick filters on a list, all joined by and (filter-toolbar).
Filtering inside a data grid's columns (data-grid).
Free-text search (search-field).

Anatomy

group: Match all / any (segmented), its rules, Add rule, Add group (up to maxDepth), remove group
rule: joining word (Where for the first; and / or after, a button that switches the group), field select, operator select, value control by type, remove
value controls: text input · number field (two for between) · date picker (two for between; a number of days for in the last) · select · multi-select · none for is empty / is true
footer: the query as a sentence, the count of matches (or Counting…), Clear

Variants

0: field types: text · number · date · select (one of a list) · multi (tags) · boolean
1: operators per field type, or a field's own subset
2: maxDepth 1 (flat, no groups) to 3
3: sentence on or off; count given or not

States

empty (one Add rule button and what it does)
rule incomplete (no value yet): marked Unfinished in words and left out of the sentence and the evaluator
counting (count null while loading): Counting…
no matches (count 0): said in words
read-only: each rule in words, no controls (the rules are the sentence)
disabled

Keyboard

Every control is the system's own field and keeps its keyboard
Adding a rule focuses its field; removing one moves focus to the next rule or to Add rule
The joining word is a button: Enter or Space switches and/or for its group

Motion

A new rule or group grows in; one removed collapses as a ghost and the rest slide up (the shared flip). Switching and/or morphs the joining word in every row of the group at once, and the group's rail changes from solid (all) to dashed (any). The count rolls to its new value. Nothing moves at rest.

Props

Prop	Type	Default	Description
`fields` (required)	`QueryField[]`	—	{ id, label, type, options?, operators?, placeholder?, unit? }
`value / defaultValue / onValueChange`	`QueryGroup`	—	{ id, combinator: "and" \| "or", rules: (QueryRule \| QueryGroup)[] }; a rule is { id, field, operator, value }.
`count`	`number \| null`	—	How many records match; null while counting. Leave out to hide.
`noun`	`[string, string]`	—	What is counted, singular and plural. Default ["record", "records"].
`maxDepth`	`number`	—	How deep groups nest; 1 means no groups. Default 2.
`sentence`	`boolean`	—	Read the query back as a sentence. Default true.
`readOnly / disabled`	`boolean`	—
`locale`	`string`	—	Numbers and dates in the sentence.
`className / classNames / style`	`string / QueryBuilderClassNames / CSSProperties`	—

Dependencies

lucide-react

Import

import { QueryBuilder } from "@/components/query-builder/query-builder";

Get it

Query builder is part of Beamline: 200+ components and 50+ complete screens for React that your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 launch price, one payment, no subscription, lifetime updates, one licence for your whole team. Get Beamline · Connect your agent