@react-querybuilder/bootstrap

@react-querybuilder/bootstrap

Official react-querybuilder compatibility package for Bootstrap.

• Demo
• Full documentation
• CodeSandbox / StackBlitz example projects

Installation

npm i react-querybuilder @react-querybuilder/bootstrap bootstrap bootstrap-icons
# OR yarn add / pnpm add / bun add

Usage

To configure the query builder to use Bootstrap-compatible components, place QueryBuilderBootstrap above QueryBuilder in the component hierarchy.

import { QueryBuilderBootstrap } from '@react-querybuilder/bootstrap';
import 'bootstrap-icons/font/bootstrap-icons.scss';
import 'bootstrap/scss/bootstrap.scss';
import { useState } from 'react';
import { type Field, QueryBuilder, type RuleGroupType } from 'react-querybuilder';

const fields: Field[] = [
  { name: 'firstName', label: 'First Name' },
  { name: 'lastName', label: 'Last Name' },
];

export function App() {
  const [query, setQuery] = useState<RuleGroupType>({ combinator: 'and', rules: [] });

  return (
    <QueryBuilderBootstrap>
      <QueryBuilder fields={fields} defaultQuery={query} onQueryChange={setQuery} />
    </QueryBuilderBootstrap>
  );
}

[!NOTE]

Some additional styling may be necessary. We recommend the following:

.queryBuilder .form-control,
.queryBuilder .form-select {
  display: inline-block;
  width: auto;
}

QueryBuilderBootstrap is a React context provider that assigns the following props to all descendant QueryBuilder elements. The props can be overridden on the QueryBuilder or used directly without the context provider.

Export	QueryBuilder prop
bootstrapControlClassnames	controlClassnames
bootstrapControlElements	controlElements
bootstrapTranslations	translations
BootstrapNotToggle	controlElements.notToggle
BootstrapValueEditor	controlElements.valueEditor

[!TIP]

By default, this package uses icons from bootstrap-icons for button labels. To reset button labels to their default strings, use defaultTranslations from react-querybuilder.

<QueryBuilderBootstrap translations={defaultTranslations}>

Changelog

[v8.8.0] - 2025-07-09

Added

• [#900] Support for matching elements of a nested array.
  • New optional RuleType property match?: { mode: MatchMode, threshold?: number }
    • type MatchMode = 'all' | 'some' | 'none' | 'atLeast' | 'atMost' | 'exactly'
    • In most contexts, a rule's operator will be ignored when match is present and valid.
  • New component MatchModeEditor, which renders when a field is determined to have one or more match modes. The mode selector is the configured valueSelector and—when a threshold is appropriate—the threshold editor is the configured valueEditor with inputType: "number".
  • New props getMatchModes and getSubQueryBuilderProps to manage these configurations at the top level.
  • New Field properties matchModes and subproperties to manage these configurations at the field level.
  • parseJsonLogic support for "all", "none", and "some" operations.
  • formatQuery (partial) support for the match rule property.
    • Supported formats include "sql", "parameterized", "drizzle", "natural_language", "mongodb_query", "jsonlogic", "jsonata", "spel", and "cel".
    • To avoid invalid syntax, the SQL-based formats only work with preset: "postgresql", and only with nested arrays of primitives like strings or numbers.
• [#903] New parser option bigIntOnOverflow. When true, a bigint will be generated for parsed tokens that represent valid integers outside the safe boundaries of the number type. (This currently only applies to parseSQL.)
• [#911] Support for inputType: "bigint" in all value editors, which will render an input with type="text" but will store the value as a bigint if a valid integer is entered.
• [#900] Extracted fields prop processing logic to new useFields hook.
• [#900] "Justified layout" styles from the demo (to push the "+ Rule", "+ Group", clone, lock, and remove buttons to the right edge) are now included in the default stylesheet. To apply the styles, add the queryBuilder-justified class to the query builder using the controlClassnames prop, or to any ancestor element.
• [#900] All components that render <label> elements now have htmlFor attributes linking their corresponding <input> elements using an id generated with useId().
• [#900] The getValueSources prop and the Field#valueSources property can now evaluate to a full option list instead of a simple array of value source strings. This enables translations of the value sources through the label property.
• [#914] Option list props (including fields, operators, combinators, getOperators, and getValues) can now include strings in addition to—or instead of—Option objects (e.g. ["=", "between"]). The string itself will be used as both the identifier and label, except in the case of operators and combinators where the default labels will be used if the string matches a value from the default set.

Fixed

• [#903] parseSQL maintains precision for large integers by generating a bigint instead of a number when necessary.
• [#900] Preact compatibility improved by using React.Fragment explicitly instead of the shorthand <>...</>.
• [#900] If the preset option for formatQuery is one from sqlDialectPresets, it will only apply if the format is undefined or one of the SQL-based formats.