React Query Builder

https://react-querybuilder.js.org/docs
Admin
React Query Builder is a fully customizable query builder component for React that enables users to...
Tokens:352,426
Snippets:2,272
Trust Score:8.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### Enable Drag and Drop setup

Source: https://react-querybuilder.js.org/docs/components/querybuilder

Installation command and implementation example for enabling drag-and-drop functionality.

```bash
npm i react-querybuilder @react-querybuilder/dnd react-dnd react-dnd-html5-backend

# OR yarn add / pnpm add / bun add
```

```javascript
import { QueryBuilderDnD } from '@react-querybuilder/dnd';

import * as ReactDnD from 'react-dnd';

import * as ReactDndHtml5Backend from 'react-dnd-html5-backend';

import { QueryBuilder } from 'react-querybuilder';



const App = () => (

  <QueryBuilderDnD dnd={{ ...ReactDnD, ...ReactDndHtml5Backend }}>

    <QueryBuilder />

  </QueryBuilderDnD>

);
```

--------------------------------

### Install with Bun

Source: https://react-querybuilder.js.org/docs/expr

Install the required packages using Bun.

```bash
bun add react-querybuilder @react-querybuilder/expr
```

--------------------------------

### Install with npm

Source: https://react-querybuilder.js.org/docs/expr

Install the required packages using npm.

```bash
npm install react-querybuilder @react-querybuilder/expr
```

--------------------------------

### Mock loader setup for compatibility examples

Source: https://react-querybuilder.js.org/docs/tips/async-option-lists

Provides a mock API call for the compatibility examples. It defines a list of words and simulates async data loading with a 500ms delay, filtering based on the input value. The getCacheKey function returns the current value.

```ts
// prettier-ignore  

const words = [ "React", "Angular", "Vue", "Svelte", "Next.js", "Nuxt.js", "Gatsby", "TypeScript", "JavaScript", "Python", "Java", "C#", "Go", "Rust", "Node.js", "Express", "Fastify", "Koa", "Hapi", "NestJS", "MongoDB", "PostgreSQL", "MySQL", "Redis", "SQLite", "Docker", "Kubernetes", "AWS", "Azure", "GCP"];  

  

// Simulate async data loading  

const loadOptionList = async (value: string | undefined): Promise<string[]> => {  

  // Simulate network delay  

  await new Promise(resolve => setTimeout(resolve, 500));  

  

  // Filter based on input value if provided  

  if (value && value.length > 0) {  

    return words.filter(word => word.toLowerCase().includes(value.toLowerCase()));  

  }  

  

  // Otherwise return no results  

  return [];  

};  

  

const getCacheKey = ({ value }: ValueEditorProps) => value;  

```

--------------------------------

### Install React Query Builder shadcn registry with Bun

Source: https://react-querybuilder.js.org/docs/compat

Installs the React Query Builder components using the shadcn CLI with Bun. Requires shadcn CLI and an existing shadcn/ui setup.

```bash
bun x shadcn add https://react-querybuilder.js.org/r/query-builder.json
```

--------------------------------

### Install with Yarn

Source: https://react-querybuilder.js.org/docs/expr

Install the required packages using Yarn.

```bash
yarn add react-querybuilder @react-querybuilder/expr
```

--------------------------------

### Install React Query Builder shadcn registry with pnpm

Source: https://react-querybuilder.js.org/docs/compat

Installs the React Query Builder components using the shadcn CLI with pnpm. Requires shadcn CLI and an existing shadcn/ui setup.

```bash
pnpm dlx shadcn add https://react-querybuilder.js.org/r/query-builder.json
```

--------------------------------

### Install with pnpm

Source: https://react-querybuilder.js.org/docs/expr

Install the required packages using pnpm.

```bash
pnpm add react-querybuilder @react-querybuilder/expr
```

--------------------------------

### Install React Query Builder shadcn registry with npm

Source: https://react-querybuilder.js.org/docs/compat

Installs the React Query Builder components into the project's configured components directory using the shadcn CLI with npm. Requires shadcn CLI and an existing shadcn/ui setup.

```bash
npx shadcn add https://react-querybuilder.js.org/r/query-builder.json
```

--------------------------------

### Install React Query Builder shadcn registry with Yarn

Source: https://react-querybuilder.js.org/docs/compat

Installs the React Query Builder components using the shadcn CLI with Yarn. Requires shadcn CLI and an existing shadcn/ui setup.

```bash
yarn dlx shadcn add https://react-querybuilder.js.org/r/query-builder.json
```

--------------------------------

### Install @react-querybuilder/migrate-raqb with Bun

Source: https://react-querybuilder.js.org/docs/api/import

Install command for the separate @react-querybuilder/migrate-raqb package using Bun.

```bash
bun add @react-querybuilder/migrate-raqb  

```

--------------------------------

### Install react-dnd packages with Bun

Source: https://react-querybuilder.js.org/docs/dnd

Install the same packages using Bun.

```bash
bun add react-querybuilder @react-querybuilder/dnd react-dnd react-dnd-html5-backend react-dnd-touch-backend  
```

--------------------------------

### Install @react-querybuilder/migrate-raqb with npm

Source: https://react-querybuilder.js.org/docs/api/import

Install command for the separate @react-querybuilder/migrate-raqb package using npm.

```bash
npm i @react-querybuilder/migrate-raqb  

```

--------------------------------

### Examples of formatQuery with presets

Source: https://react-querybuilder.js.org/docs/utils/export

Two examples showing formatQuery with the 'postgresql' and 'mssql' presets, including their output.

```javascript
formatQuery(query, { format: 'parameterized', preset: 'postgresql' });

/*

{

  sql: `("firstName" like $1 and "lastName" in ($2, $3))`,

  params: ['Stev%', 'Vai', 'Vaughan']

}

*/



formatQuery(query, { format: 'sql', preset: 'mssql' });

/*

"([musicians].[firstName] = 'Kris' and [musicians].[lastName] like [musicians].[firstName] + '%')"

*/
```

--------------------------------

### getOption usage examples

Source: https://react-querybuilder.js.org/docs/tips/option-lists

Examples showing how to retrieve an option object from both flat and grouped option lists.

```javascript
getOption(  
  [  
    { name: 'firstName', label: 'First Name' },  
    { name: 'lastName', label: 'Last Name' },  
  ],  
  'lastName'  
);  
// => { name: 'lastName', label: 'Last Name' }

getOption(  
  [  
    { label: 'First', options: [{ name: 'firstName', label: 'First Name' }] },  
    { label: 'Last', options: [{ name: 'lastName', label: 'Last Name' }] },  
  ],  
  'lastName'  
);  
// => { name: 'lastName', label: 'Last Name' }
```

--------------------------------

### Install @react-querybuilder/migrate-raqb with Yarn

Source: https://react-querybuilder.js.org/docs/api/import

Install command for the separate @react-querybuilder/migrate-raqb package using Yarn.

```bash
yarn add @react-querybuilder/migrate-raqb  

```

--------------------------------

### Install @react-querybuilder/migrate-raqb with pnpm

Source: https://react-querybuilder.js.org/docs/api/import

Install command for the separate @react-querybuilder/migrate-raqb package using pnpm.

```bash
pnpm add @react-querybuilder/migrate-raqb  

```

--------------------------------

### Install react-dnd packages with npm

Source: https://react-querybuilder.js.org/docs/dnd

Install react-querybuilder, @react-querybuilder/dnd, react-dnd, react-dnd-html5-backend, and react-dnd-touch-backend using npm.

```bash
npm i react-querybuilder @react-querybuilder/dnd react-dnd react-dnd-html5-backend react-dnd-touch-backend  
```

--------------------------------

### Install Drag and Drop dependencies

Source: https://react-querybuilder.js.org/docs/api/querybuilder

Install the required packages to enable drag-and-drop functionality in the query builder.

```bash
npm i react-querybuilder @react-querybuilder/dnd react-dnd react-dnd-html5-backend  

# OR yarn add / pnpm add / bun add  
```

--------------------------------

### Install react-dnd packages with Yarn

Source: https://react-querybuilder.js.org/docs/dnd

Install the same packages using Yarn.

```bash
yarn add react-querybuilder @react-querybuilder/dnd react-dnd react-dnd-html5-backend react-dnd-touch-backend  
```

--------------------------------

### Install react-dnd packages with pnpm

Source: https://react-querybuilder.js.org/docs/dnd

Install the same packages using pnpm.

```bash
pnpm add react-querybuilder @react-querybuilder/dnd react-dnd react-dnd-html5-backend react-dnd-touch-backend  
```

--------------------------------

### getFirstOption usage examples

Source: https://react-querybuilder.js.org/docs/tips/option-lists

Examples showing how to retrieve the identifier of the first option in flat and grouped lists.

```javascript
getFirstOption([  
  { name: 'firstName', label: 'First Name' },  
  { name: 'lastName', label: 'Last Name' },  
]);  
// => 'firstName'

getFirstOption([  
  { label: 'First', options: [{ name: 'firstName', label: 'First Name' }] },  
  { label: 'Last', options: [{ name: 'lastName', label: 'Last Name' }] },  
]);  
// => 'firstName'
```

--------------------------------

### Install @atlaskit/pragmatic-drag-and-drop dependencies

Source: https://react-querybuilder.js.org/docs/dnd

Installation commands for the Pragmatic drag-and-drop adapter using various package managers.

```bash
npm i react-querybuilder @react-querybuilder/dnd @atlaskit/pragmatic-drag-and-drop
```

```bash
bun add react-querybuilder @react-querybuilder/dnd @atlaskit/pragmatic-drag-and-drop
```

```bash
yarn add react-querybuilder @react-querybuilder/dnd @atlaskit/pragmatic-drag-and-drop
```

```bash
pnpm add react-querybuilder @react-querybuilder/dnd @atlaskit/pragmatic-drag-and-drop
```

--------------------------------

### Install @dnd-kit dependencies

Source: https://react-querybuilder.js.org/docs/dnd

Installation commands for the dnd-kit adapter using various package managers.

```bash
npm i react-querybuilder @react-querybuilder/dnd @dnd-kit/core
```

```bash
bun add react-querybuilder @react-querybuilder/dnd @dnd-kit/core
```

```bash
yarn add react-querybuilder @react-querybuilder/dnd @dnd-kit/core
```

```bash
pnpm add react-querybuilder @react-querybuilder/dnd @dnd-kit/core
```

--------------------------------

### parseRAQB output example

Source: https://react-querybuilder.js.org/docs/api/import

Example RuleGroupType output from parseRAQB, showing an 'and' combinator with a rule for price greater than 10.

```json
{  
  "combinator": "and",  
  "rules": [{ "field": "price", "operator": ">", "value": 10 }]  
}  

```

--------------------------------

### Natural language preset example

Source: https://react-querybuilder.js.org/docs/utils/export

Example of a natural language query preset that starts with First Name 'Stev' and is greater than Age '28'.

```text
// yn dechrau gyda First Name 'Stev', a yn fwy na Age '28'
```

--------------------------------

### Use native format to get an in-process evaluator

Source: https://react-querybuilder.js.org/docs/rules-engine

Converts rulesEngine to the 'native' format, returning a dependency-free evaluator function with signature (facts) => Consequent[]. The example shows calling the evaluator with facts and the resulting consequents array.

```javascript
import { formatRulesEngine } from '@react-querybuilder/rules-engine';  

  

const evaluate = formatRulesEngine(rulesEngine, 'native');  

  

const firedConsequents = evaluate({ temperature: 90, humidity: 35 });  

// => [{ type: 'alert', message: 'High temperature detected' }]  
```

--------------------------------

### Custom rule processor for JSONata date handling

Source: https://react-querybuilder.js.org/docs/utils/export

A custom rule processor for JSONata that handles date values by using $toMillis. It checks the field's datatype property (non-standard) and falls back to defaultRuleProcessorJSONata otherwise. The example lacks error checking and is a starting point.

```typescript
const customRuleProcessor: RuleProcessor = (rule, options) => {

  // `datatype` is a non-standard property of the field, used for this example only.

  // Replace this condition with your own logic to determine if the value is a date.

  if (options?.fieldData?.datatype === 'date') {

    return `$toMillis(${rule.field}) ${rule.operator} $toMillis("${rule.value}")`;

  }

  return defaultRuleProcessorJSONata(rule, options);

};
```

--------------------------------

### Install react-querybuilder with Bun

Source: https://react-querybuilder.js.org/docs/intro

Use Bun to add the package to your project.

```bash
bun add react-querybuilder
```

--------------------------------

### isOptionGroupArray usage examples

Source: https://react-querybuilder.js.org/docs/tips/option-lists

Examples demonstrating the isOptionGroupArray type guard.

```javascript
isOptionGroupArray([  
  { value: 'firstName', label: 'First Name' },  
  { value: 'lastName', label: 'Last Name' },  
]);  
// => false

isOptionGroupArray([  
  { label: 'First', options: [{ value: 'firstName', label: 'First Name' }] },  
  { label: 'Last', options: [{ value: 'lastName', label: 'Last Name' }] },  
]);  
// => true
```

--------------------------------

### toOptions OptionGroup[] example

Source: https://react-querybuilder.js.org/docs/tips/option-lists

Example of toOptions converting a grouped array of options.

```javascript
toOptions([  
  { label: 'First', options: [{ value: 'firstName', label: 'First Name' }] },  
  { label: 'Last', options: [{ value: 'lastName', label: 'Last Name' }] },  
]);  
// yields (approximately):  
[  
  <optgroup key={'First'} label={'First'}>  
    <option key={'firstName'} value={'firstName'}>  
      First Name  
    </option>  
  </optgroup>,  
  <optgroup key={'Last'} label={'Last'}>  
    <option key={'lastName'} value={'lastName'}>  
      Last Name  
    </option>  
  </optgroup>,  
];
```

--------------------------------

### Install react-querybuilder with npm

Source: https://react-querybuilder.js.org/docs/intro

Use npm to add the package to your project.

```bash
npm i react-querybuilder
```

--------------------------------

### toOptions Option[] example

Source: https://react-querybuilder.js.org/docs/tips/option-lists

Example of toOptions converting a flat array of options.

```javascript
toOptions([  
  { value: 'firstName', label: 'First Name' },  
  { value: 'lastName', label: 'Last Name' },  
]);  
// yields (approximately):  
[  
  <option key={'firstName'} value={'firstName'}>  
    First Name  
  </option>,  
  <option key={'lastName'} value={'lastName'}>  
    Last Name  
  </option>,  
];
```

--------------------------------

### Configuring Drizzle and Sequelize Processors

Source: https://react-querybuilder.js.org/docs/expr

Shows how to provide the necessary context helpers for library-backed formats like Drizzle and Sequelize.

```javascript
import { getOperators } from 'drizzle-orm';  

import { col, literal, Op, where } from 'sequelize';  

import {  

  expressionRuleProcessorDrizzle,  

  expressionRuleProcessorSequelize,  

} from '@react-querybuilder/expr';  

  

const drizzleWhere = formatQuery(query, {  

  format: 'drizzle',  

  preset: 'sqlite', // resolves min/max to MIN/MAX (else LEAST/GREATEST)  

  ruleProcessor: expressionRuleProcessorDrizzle,  

  context: { columns, drizzleOperators: getOperators() },  

});  

  

const sequelizeWhere = formatQuery(query, {  

  format: 'sequelize',  

  preset: 'sqlite',  

  ruleProcessor: expressionRuleProcessorSequelize,  

  context: {  

    sequelizeOperators: Op,  

    sequelizeWhere: where,  

    sequelizeLiteral: literal,  

    sequelizeCol: col,  

  },  

});
```

--------------------------------

### Example RAQB input and RQB output

Source: https://react-querybuilder.js.org/docs/tips/migrate-from-raqb

Shows a sample RAQB plain-JSON tree and the resulting RQB query. Both children1 shapes (array and keyed-object) are supported.

```javascript
parseRAQB({  
  type: 'group',  
  properties: { conjunction: 'AND' },  
  children1: [  
    {  
      type: 'rule',  
      properties: { field: 'price', operator: 'greater', value: [10], valueSrc: ['value'] },  
    },  
    {  
      type: 'rule',  
      properties: { field: 'color', operator: 'select_any_in', value: [['yellow', 'green']] },  
    },  
  ],  
});  

```

```json
{  
  "combinator": "and",  
  "rules": [  
    { "field": "price", "operator": ">", "value": 10 },  
    { "field": "color", "operator": "in", "value": "yellow,green" }  
  ]  
}  

```

--------------------------------

### Install react-querybuilder with Yarn

Source: https://react-querybuilder.js.org/docs/intro

Use Yarn to add the package to your project.

```bash
yarn add react-querybuilder
```

--------------------------------

### Example output object with numbered placeholders

Source: https://react-querybuilder.js.org/docs/tips/custom-bind-variables

The resulting object after applying the custom replacement logic.

```json
{

  "sql": "(firstName = $1 and lastName = $2)",

  "params": ["Steve", "Vai"]

}
```

--------------------------------

### prepareOptionList

Source: https://react-querybuilder.js.org/docs/utils/framework-adapters

Normalizes any option list prop into a FullOptionList, applying placeholders.

```APIDOC
## prepareOptionList

### Description
Normalizes any option list prop into a `FullOptionList`, applying placeholders.

### Method
Function

### Signature
`prepareOptionList(optionList)`

### Parameters
- **optionList** (any) - Required - The option list prop to normalize.

### Returns
- `FullOptionList` - The normalized option list with placeholders applied.
```

--------------------------------

### Cache key design examples

Source: https://react-querybuilder.js.org/docs/tips/async-option-lists

Shows bad and good cache key designs. The bad example includes the selector's own value, which is discouraged unless building auto-complete. The good example uses context-dependent keys without the own value.

```javascript
// ❌ Bad: includes own value (unless auto-complete)  

getCacheKey: props => `${props.rule?.field}-${props.value}`;  

  

// ✅ Good: context-dependent without own value  

getCacheKey: props => `operators-${props.rule?.field}`;  
```

--------------------------------

### Install react-querybuilder with pnpm

Source: https://react-querybuilder.js.org/docs/intro

Use pnpm to add the package to your project.

```bash
pnpm add react-querybuilder
```

--------------------------------

### parseGremlin output example

Source: https://react-querybuilder.js.org/docs/api/import

Example RuleGroupType output from parseGremlin, showing an 'and' combinator with rules for age and name.

```json
{  
  "combinator": "and",  
  "rules": [  
    { "field": "age", "operator": ">", "value": 30 },  
    { "field": "name", "operator": "=", "value": "Alice" }  
  ]  
}  

```
Tokens:
Raw