Getting Started

Builder Behavior

A few builder props shape the overall editing model more than the field or query data itself. These are worth deciding early because they affect how users add, move, and organize rules.

Builder behavior

import '@vojtechportes/react-query-builder/styles.css';
<Builder
  fields={fields}
  data={data}
  useDefaultContainerStyles={false}
  lockable
  readOnlyProtectsDelete
  cloneable
  draggable
  allowGroupNegation={false}
  newNodePlacement="prepend"
  singleRootGroup={false}
  groupTypes="both"
  onChange={setData}
/>;

// useDefaultContainerStyles={false}:
// Keeps the Builder root div and baseline typography, but omits its padding,
// background, border, radius, and shadow so an application wrapper can provide
// the container presentation.
//
// lockable:
// Renders built-in lock controls for rules and groups and writes the resulting
// lock state back into the emitted query via rule/group readOnly values.
//
// readOnlyProtectsDelete:
// Prevents deleting parent groups when that delete would indirectly remove
// read-only protected descendants. Defaults to true.
//
// cloneable:
// Renders built-in clone controls for rules and groups and inserts the cloned
// node directly below the original node.
//
// draggable:
// Enables drag-and-drop for editable rules and groups.
//
// allowGroupNegation={false}:
// Hides the group-level NOT toggle and rejects NOT (...) groups in text mode
// while still allowing operator-level negation such as NOT IN or IS NOT NULL.
//
// newNodePlacement="prepend":
// Inserts newly added rules and groups at the beginning of their parent instead
// of appending them to the end. The default is "append".
//
// singleRootGroup={false}:
// Allows multiple root-level nodes instead of wrapping everything into one root group.
//
// groupTypes="both":
// Lets users choose between groups with AND/OR/NOT controls and groups without modifiers.

useDefaultContainerStyles

Defaults to true and renders the outer surface with the Builder root padding, background, border, radius, and shadow.
Set useDefaultContainerStyles={false} when an application wrapper already provides that surface. The Builder's baseline color, font, size, and line height remain active so built-in controls keep their normal dimensions.
The root div remains in the DOM when default styles are disabled, so className, style, CSS variables, and colorScheme still have a stable target.

cloneable

Defaults to false and renders built-in clone controls for rules and groups.
The clone button appears immediately to the left of the lock button when both controls are enabled.
Cloning a rule inserts a duplicate directly below that rule.
Cloning a group duplicates the entire subtree and inserts the clone directly below that group.
When singleRootGroup is enabled, the synthetic root group does not expose a clone control.

draggable

Use lockable to expose lock controls directly in the UI.
Enables drag-and-drop reordering and movement for editable rules and groups.
Read-only rules and groups are excluded from dragging.
When the entire builder is read-only, drag-and-drop is disabled as well.
Empty groups expose a dedicated drop zone so items can be moved into them.

readOnlyProtectsDelete

Defaults to true.
When enabled, deleting a group is blocked if that would indirectly remove read-only protected descendants.
Set it to false when your product wants only directly protected nodes to be non-deletable, while still allowing parent-group deletes around them.

singleRootGroup

Defaults to true, which means the builder maintains a single root group around the visible tree.
The root group cannot be deleted while singleRootGroup is enabled.
Set it to false when your application wants multiple top-level nodes instead of one wrapped root group.

newNodePlacement

Defaults to 'append', which inserts newly added rules and groups at the end of their parent.
Set it to 'prepend' to insert new rules and groups at the beginning of their parent instead.
This affects built-in Add Rule and Add Group controls, root-level add controls, and imperative ref methods when no explicit index is provided.
It does not change cloning or drag-and-drop behavior, since those actions already use explicit target positions.

groupTypes

with-modifiers shows group controls such as AND, OR, and negation.
without-modifiers creates structural groups that do not render combinator or negation controls.
both lets users choose which group kind to insert when adding a new group.

allowGroupNegation

Set allowGroupNegation= when you want groups to keep combinators like AND and OR but remove the group-level NOT option.
This is narrower than groupTypes: it only disables negating whole groups and does not affect whether groups render combinator controls.
Operator-level negation still works normally, including NOT IN, NOT LIKE, IS NOT NULL, and NOT BETWEEN.
When disabled, incoming negated groups are normalized to non-negated form so the builder output stays consistent with the visible UI.