# QueryBuilder

Source: https://lumeo.nativ.sh/components/query-builder

# QueryBuilder

A visual AND/OR predicate-tree builder — compose nested conditions over a set of fields and serialize them to JSON or a LINQ predicate.

## When to Use

-   Let users build advanced filters or saved searches over a dataset.
-   Capture rules for report definitions, automation triggers, segmentation, or audience targeting.
-   Produce a structured query you can send to a backend (the JSON shape) or run client-side (the LINQ predicate).
-   For a single column's quick filter, prefer the DataGrid's built-in column filter; reach for QueryBuilder when conditions span multiple fields with nested AND/OR logic.

Preview Code

Basic builder

AND OR

Rule Group

NameEmailAgeSignup dateActivePlanequalsnot equalscontainsdoes not containstarts withends withis emptyis not empty

NameEmailAgeSignup dateActivePlanequalsnot equalsless thanless than or equalgreater thangreater than or equalbetweenis nullis not null

Copy Code

Preview Code

With JSON preview

AND OR

Rule Group

NameEmailAgeSignup dateActivePlanequalsnot equalsinnot inis nullis not nullFreeProEnterprise

NameEmailAgeSignup dateActivePlanequalsnot equalstrue

JSON

```
{
  "combinator": "And",
  "rules": [
    {
      "$type": "rule",
      "field": "plan",
      "operator": "=",
      "value": "pro",
      "value2": null
    },
    {
      "$type": "rule",
      "field": "isActive",
      "operator": "=",
      "value": true,
      "value2": null
    }
  ]
}
```

Copy Code

Preview Code

Pre-populated nested groups

AND OR

Rule Group

NameEmailAgeSignup dateActivePlanequalsnot equalstrue

AND OR

Rule Group

NameEmailAgeSignup dateActivePlanequalsnot equalsinnot inis nullis not nullFreeProEnterprise

NameEmailAgeSignup dateActivePlanequalsnot equalsinnot inis nullis not nullFreeProEnterprise

AND OR

Rule Group

NameEmailAgeSignup dateActivePlanequalsnot equalsless thanless than or equalgreater thangreater than or equalbetweenis nullis not nulland

Copy Code

## API Reference

### QueryBuilder

Property

Type

Default

Description

Fields

IReadOnlyList<QueryField>

\[\]

The fields the user can build conditions against. Required.

Query

QueryGroup?

null

The query tree. Use with `@bind-Query`. When null on first render, an empty root group (And, no rules) is created.

QueryChanged

EventCallback<QueryGroup>

—

Fires whenever the tree changes (add/remove rule or group, combinator, field, operator, value).

ShowJsonPreview

bool

false

When true, renders a read-only JSON view of the query below the builder.

MaxDepth

int

5

Maximum group nesting depth. "Add group" is disabled at this depth.

AllowEmptyGroups

bool

true

When false, "Remove rule"/"Remove group" are hidden when removal would leave a group empty (the root may always be empty).

ValueEditorTemplate

RenderFragment<QueryRule>?

null

Optional override for a rule's value editor. When set, replaces the built-in per-type editor; the consumer binds to `QueryRule.Value` and notifies via the cascaded context.

Class

string?

null

Extra CSS classes for the root element.

Static helpers: `QueryBuilder.ToJson(query)` · `QueryBuilder.FromJson(json)` · `QueryBuilder.ToExpression<T>(query)` (returns `Expression<Func<T,bool>>?` — null for an empty tree).

### QueryField

Property

Type

Description

Name

string

Stable key written to `QueryRule.Field`. Required.

Label

string?

Human-facing label in the field picker. Falls back to `Name`.

Type

QueryFieldType

`Text`, `Number`, `Date`, `Boolean`, or `Select`. Determines the default operator set and the built-in value editor.

Operators

IReadOnlyList<string>?

Allowed operator keys. Null = the default set for `Type`.

Options

IReadOnlyList<(string Value, string Label)>?

Options shown when `Type` is `Select`.

### QueryRule / QueryGroup / QueryNode

Member

Type

Description

QueryNode

abstract

Base of the tree — either a `QueryRule` (leaf) or a `QueryGroup` (branch).

QueryRule.Field

string

The `QueryField.Name` this rule targets.

QueryRule.Operator

string

One of the field's allowed operator keys.

QueryRule.Value / Value2

object?

The comparison value(s). `Value2` is used only by range operators ("between").

QueryGroup.Combinator

QueryCombinator

`And` or `Or` — applied across `Rules`.

QueryGroup.Rules

List<QueryNode>

Child rules and/or nested groups.

QueryGroup.CreateEmpty()

static

A new empty root group (And, no rules).

### Default operator sets

Field type

Operators (key → label)

Text

`=` equals, `!=` not equals, `contains`, `notContains`, `startsWith`, `endsWith`, `isEmpty`, `isNotEmpty`

Number

`=`, `!=`, `<` less than, `<=`, `>` greater than, `>=`, `between`, `isNull`, `isNotNull`

Date

`=`, `!=`, `<`, `<=`, `>`, `>=`, `between`, `isNull`, `isNotNull`

Boolean

`=`, `!=`

Select

`=`, `!=`, `in`, `notIn`, `isNull`, `isNotNull` (`in`/`notIn` take a comma-separated value)

`isEmpty` / `isNotEmpty` / `isNull` / `isNotNull` render no value editor; `between` renders two. Override the set per field via `QueryField.Operators`.

## Related Components

-   [DataGrid](/components/data-grid) — Apply the produced query as a server- or client-side filter over tabular data.
-   [Filter](/components/filter) — A lighter, single-level filter bar when nested AND/OR logic isn't needed.
-   [Select](/components/select) — The picker primitive; QueryBuilder uses native selects internally for compact rule rows.