All components (244)

Query builder

Management · QueryBuilder

What it is and when to use it

A query builder with nested groups: "field, operator, value" conditions joined by "and" or "or", with groups inside groups and the option to negate a group.

When to use it

A filter that does not fit in a couple of dropdowns: "amount over 100 and (customer starts with Ac or not collected)".
fields are the fields, each with its type (text, number, date or boolean): the type decides the operators and the value field.
It hands out a data tree (QueryGroup) through onChange. To apply it on the client, filterByQuery(records, query, fields, read); on the server the same tree is walked.
value makes it controlled; without it, it starts from initialValue. maxDepth limits how many groups fit inside one another (5 at most).
A half-built condition (no value) filters nothing, so it can be put together without emptying the list.

When not to

A simple filter of a table: the advanced filters panel of Table, which uses the same condition logic.
Free-text search: a search field.
The tree is not validated against the server: whoever receives it decides which fields and operators it accepts.

Keyboard: it is a set of normal controls; Tab goes through each group in order, and each change of structure (adding or removing) is announced.

Accessibility: each group is a named group ("Group 2"); each condition numbers its fields ("Value of condition 3"). The negation and the "and/or" are labelled controls, not just colour: the group's stripe changes, but its checkbox says so too.

Fine appearance: each group is a box with a stripe on the left in the accent colour, or the error colour if negated; conditions wrap onto several lines when they do not fit.

What it looks like

Matches

Negate the group

Field of condition 1
Customer
Status
Total (€)
Operator of condition 1
contains
does not contain
is equal to
is not equal to
starts with
is empty
is not empty
Value of condition 1
Paid
Pending
Shipped
Field of condition 2
Customer
Status
Total (€)
Operator of condition 2
is equal to
is not equal to
greater than
greater than or equal to
less than
less than or equal to
between
is empty
is not empty
Value of condition 2

2 active conditions

Show the query as

LOWER("estado") = ? AND "total" > ?
-- parameters: ["pagado",100]

1 of 5 orders match the query.

<QueryBuilder
  label="Which orders to find"
  fields={campos}
  value={consulta}
  onChange={setConsulta}
  summary
  exports={["sql", "text"]}
/>

Props

Import it with import { QueryBuilder } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`fields`required	`readonly QueryField[]`	The fields that can be filtered by, with their type: the type decides the operators and the value field.
`label`required	`string`	Which query it is («Invoice filter»): it names the builder for whoever uses a screen reader. Required.
`className`	`string`	Merged with the library classes; it does not replace them.
`disabled`	`boolean`	—
`exports`	`readonly QueryExportFormat[]`	Under the builder, the query written out in these formats (one at a time, chosen from a list): `sql` (a `WHERE` with its parameters), `mongo` (a filter) and `text` (a sentence). The same text comes from `queryToSql`, `queryToMongo` and `queryToText`, to use the query on the server. Not shown by default.
`initialValue`	`QueryGroup`	—
`maxDepth`	`number`	How many groups can be put inside one another, counting the root. 5 by default, which is also the limit.
`onChange`	`(value: QueryGroup) => void`	—
`readOnly`	`boolean`	It can be seen and moved through, but it does not change.
`summary`	`boolean`	The count of active conditions under the builder. On by default.
`value`	`QueryGroup`	The query. If passed, the builder is controlled.

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: