Builder

export interface IBuilderProps {
  fields: IBuilderFieldProps[];
  data: DenormalizedQuery;
  className?: string;
  style?: IBuilderStyle;
  useDefaultContainerStyles?: boolean;
  colorScheme?: 'light' | 'dark';
  components?: IBuilderComponentsProps;
  strings?: IStrings;
  textMode?: boolean | IBuilderTextModeConfig;
  defaultMode?: BuilderDefaultMode;
  readOnly?: boolean;
  readOnlyProtectsDelete?: boolean;
  lockable?: boolean;
  cloneable?: boolean;
  draggable?: boolean;
  allowGroupNegation?: boolean;
  allowFieldComparisons?: boolean;
  singleRootGroup?: boolean;
  groupTypes?: 'with-modifiers' | 'without-modifiers' | 'both';
  newNodePlacement?: 'append' | 'prepend';
  validator?: IBuilderValidator;
  onStateChange?: (state: IBuilderStateChange) => void;
  onFieldOptionsReload?: (field: string) => void;
  onRuleOptionsReload?: (ruleId: string) => void;
  onFieldChange?: (change: IBuilderFieldChange) => void;
  showValidation?: boolean;
  history?: boolean | IBuilderHistoryConfig;
  onChange?: (data: DenormalizedQuery) => any;
}

export interface IBuilderHistoryConfig {
  maxEntries?: number;
  controls?: boolean;
}

Props

• fields Required. Defines the available fields, their types, allowed operators, and optional validation metadata.
• data Required. The current denormalized query tree. The builder treats this as controlled input.
• Ref support Builder supports React refs and can be paired with useBuilderRef() for imperative access.
• components Optional overrides for internal UI pieces. Omitted entries fall back to default components.
• strings Optional localized UI strings used by the built-in controls.
• textMode Optional. Enables SQL text mode. Pass true for the default configuration or IBuilderTextModeConfig for explicit SQL text-mode settings.
• defaultMode Optional. Controls whether the builder initially opens in 'builder' or 'text' mode. This only takes effect when text mode is enabled.
• readOnly Defaults to false. Makes the whole builder non-editable.
• readOnlyProtectsDelete Defaults to true. When enabled, groups cannot be deleted if that would indirectly remove read-only protected descendants. Set it to false to allow those parent-group deletes while keeping direct read-only node restrictions.
• lockable Defaults to false. Renders lock controls for rules and groups and writes the resulting lock state back into emitted query data without discarding existing targeted readOnly.targets configurations.
• cloneable Defaults to false. Renders clone controls for rules and groups and inserts the cloned node directly below the original.
• draggable Defaults to false. Enables drag-and-drop reordering and movement of query nodes.
• useDefaultContainerStyles Defaults to true. Set it to false to omit the built-in root surface styles while retaining the baseline typography and color styles. The root div, className, style, and data attributes remain available.
• colorScheme Optional 'light' | 'dark' built-in component scheme. Dark mode requires importing @vojtechportes/react-query-builder/dark-mode.variables.css. Leave this undefined to preserve inherited application variables.
• allowGroupNegation Defaults to true. When set to false, group negation is disabled across the builder: the group-level NOT control is hidden, emitted groups are normalized to non-negated form, and SQL text mode rejects group-level NOT (...) expressions. Operator-level negation such as NOT IN, NOT LIKE, IS NOT NULL, and NOT BETWEEN remains supported.
• allowFieldComparisons Defaults to false. Enables the built-in value-source toggle so supported rules can compare one field against another through valueSource: 'field' and valueField.
• singleRootGroup Defaults to true. Wraps root-level items into a single root group and prevents deleting that root group. Text mode requires this to stay enabled.
• groupTypes Defaults to 'with-modifiers'. Controls whether groups use combinator/negation controls, modifierless groups, or both. When text mode is active, builder-compatible SQL round-tripping uses groups with modifiers.
• newNodePlacement Defaults to 'append'. Controls whether newly added rules and groups are inserted at the end or the beginning of their parent when built-in add actions or imperative add methods omit an explicit index.
• validator Optional function that receives the denormalized query plus validation context and returns a validation result synchronously or asynchronously.
• onStateChange Optional callback fired with data, isValid, the full validation object, and history state flags such as canUndo and canRedo.
• onFieldOptionsReload Optional callback fired by reloadFieldOptions(field) for shared field-level runtime options.
• onRuleOptionsReload Optional callback fired by reloadRuleOptions(ruleId) for dependency-aware rule-level runtime options.
• onFieldChange Optional callback fired with node id, field name, previous value, next value, and denormalized data after a rule field or value changes.
• showValidation Defaults to false. Controls whether validation issues are rendered in the built-in UI.
• history Optional. Set to true to enable undo and redo with default settings, or pass IBuilderHistoryConfig to customize retention and built-in controls.
• onChange Optional callback fired with the denormalized query tree after changes are emitted.

Field comparisons

import '@vojtechportes/react-query-builder/styles.css';
const data: DenormalizedQuery = [
  {
    type: 'GROUP',
    value: 'AND',
    isNegated: false,
    children: [
      {
        field: 'ORDER_TOTAL',
        operator: 'LARGER_EQUAL',
        valueSource: 'field',
        valueField: 'ORDER_APPROVAL_LIMIT',
      },
    ],
  },
];

<Builder
  allowFieldComparisons
  fields={fields}
  data={data}
  onChange={setData}
/>;

• Opt-in The default UI exposes field-to-field comparisons only when allowFieldComparisons is enabled.
• Persisted data Preloaded field-comparison rules stay representable through valueSource and valueField, even though validation will block them when the prop is disabled.

Text mode behavior

export interface IBuilderTextModeConfig {
  format?: 'SQL';
  defaultMode?: BuilderDefaultMode;
}

export type BuilderDefaultMode = 'builder' | 'text';

• Format The current text-mode implementation edits SQL.
• Config shape textMode accepts either true or { format?: 'SQL'; defaultMode?: 'builder' | 'text' }.
• Default-mode precedence If both textMode.defaultMode and the top-level defaultMode prop are provided, the top-level prop wins.
• Syntax and semantic validation The built-in editor highlights invalid SQL syntax plus builder-specific issues such as unknown fields, unsupported operators, and invalid select values.
• Field comparisons When allowFieldComparisons is enabled, SQL text mode accepts builder-compatible right-hand-side field references such as ORDER_TOTAL >= ORDER_APPROVAL_LIMIT. When disabled, the same expression is reported as a semantic validation issue.
• Invalid text flow Invalid text stays local to text mode, the last valid builder query is preserved, and onChange is fired only after a valid parse and semantic validation.
• History Valid text edits are committed into builder history. Invalid intermediate text is not committed into builder state or history.
• Built-in editor Included in the main package and suitable for freely editable SQL text mode.
• Locked queries The built-in text editor blocks locked or targeted read-only queries because it cannot preserve protected text ranges safely after freeform edits.
• Custom editors Custom text editors receive protectedRanges so localized read-only SQL fragments can stay visible while remaining non-editable.
• Monaco path Use the optional @vojtechportes/react-query-builder/monaco subpackage when you need a protected-range editor that can preserve locked and targeted read-only query segments.

History config

• maxEntries Optional limit for how many undo steps are retained.
• controls Optional toggle for rendering the built-in Undo and Redo buttons inside the builder UI.