@react-querybuilder/dnd

@react-querybuilder/dnd

Augments react-querybuilder with drag-and-drop functionality.

To see this in action, check out the react-querybuilder demo with the drag-and-drop option enabled.

Full documentation

Installation

npm i react-querybuilder @react-querybuilder/dnd react-dnd react-dnd-html5-backend
# OR yarn add / pnpm add / bun add

Usage

To enable the drag-and-drop functionality of a query builder, nest the QueryBuilder element under QueryBuilderDnD. Pass in all exports from react-dnd and either react-dnd-html5-backend or react-dnd-touch-backend to the dnd prop of QueryBuilderDnD. (If you pass in all exports from both backends, the touch backend will be preferred when a touch device is detected.)

import { QueryBuilderDnD } from '@react-querybuilder/dnd';
import { useState } from 'react';
import * as ReactDnD from 'react-dnd';
import * as ReactDndBackend from 'react-dnd-html5-backend';
// OR
// import * as ReactDndBackend from 'react-dnd-touch-backend';
import { QueryBuilder, RuleGroupType } from 'react-querybuilder';

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

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

  return (
    <QueryBuilderDnD dnd={{ ...ReactDnD, ...ReactDndBackend }}>
      <QueryBuilder fields={fields} defaultQuery={query} onQueryChange={setQuery} />
    </QueryBuilderDnD>
  );
};

Notes

• While not strictly necessary, we strongly recommend passing the react-dnd and react-dnd-html5-backend/react-dnd-touch-backend exports into QueryBuilderDnD. If they are not passed in as the dnd prop, the query builder will initially have drag-and-drop disabled until the dependencies are asynchronously loaded via import().

• QueryBuilderDnD will automatically set the enableDragAndDrop prop to true on any descendant QueryBuilder elements unless enableDragAndDrop is explicitly set to false on QueryBuilder.

• QueryBuilderDnD does not need to be an immediate ancestor to QueryBuilder, it only needs to be somewhere above QueryBuilder in the component hierarchy.

• Multiple QueryBuilders may be nested beneath a single QueryBuilderDnD. The same drag-and-drop settings will be applied to each query builder, and drag-and-drop will work across query builders (rules/groups can be dragged from one query builder and dropped into another).

• If your application already uses react-dnd outside the scope of a query builder, use QueryBuilderDndWithoutProvider instead of QueryBuilderDnD to inherit context from your existing DndProvider. Example:

  import { QueryBuilderDndWithoutProvider } from '@react-querybuilder/dnd';
  import { useState } from 'react';
  import * as ReactDnD from 'react-dnd';
  import * as ReactDndBackend from 'react-dnd-html5-backend';
  import { type Field, QueryBuilder, type RuleGroupType } from 'react-querybuilder';
  import { SomeOtherDndContextConsumer } from './SomeOtherDndContextConsumer';
  
  const fields: Field[] = [
    { name: 'firstName', label: 'First Name' },
    { name: 'lastName', label: 'Last Name' },
  ];
  
  function ChildComponentOfDndProvider() {
    const [query, setQuery] = useState<RuleGroupType>({ combinator: 'and', rules: [] });
  
    return (
      <QueryBuilderDndWithoutProvider dnd={{ ...ReactDnD, ...ReactDndBackend }}>
        <QueryBuilder fields={fields} defaultQuery={query} onQueryChange={setQuery} />
      </QueryBuilderDndWithoutProvider>
    );
  }
  
  export function App() {
    return (
      <ReactDnD.DndProvider backend={ReactDndBackend.HTML5Backend}>
        <SomeOtherDndContextConsumer />
        <ChildComponentOfDndProvider />
      </ReactDnD.DndProvider>
    );
  }
  

Changelog

[v8.5.0] - 2025-04-07

Added

• [#873] New prop autoSelectValue (documentation) behaves like autoSelectField/autoSelectOperator but for the value editor when it renders a select list.
  • The translations prop object has a new property values that accepts placeholderName, placeholderLabel, and placeholderGroupLabel properties (documentation). These translatable strings set the default values and labels when autoSelectValue is set to false.
  • A corresponding placeholderValueName option was added to formatQuery, which will now ignore rules where the value matches the placeholder value as long as placeholderValueName is defined (this behavior differs from placeholderFieldName and placeholderOperatorName, which do not need to be defined).
• [#876] Miscellaneous i18n enhancements for the "natural_language" export format:
  • translations option: Map of the words "and", "or", "true", and "false" to their translated equivalents. Also covers prefix and suffix options for rule groups.
  • wordOrder option: Based on the linguistic concept of constituent word order, this option accepts all permutations of "SVO" ("SOV", "VSO", etc.) and outputs the field, operator, and value in the corresponding order (S = field, V = operator, O = value).
  • operatorMap option: Map of operators to their natural language equivalents. If the result can differ based on the valueSource, the key should map to an array where the second element represents the string to be used when valueSource is "field". The first element will be used in all other cases.
  • Date/time formatting support: The @react-querybuilder/datetime package now supports the "natural_language" format for date-type rules. Formatting can be customized by passing locales, dateFormat, or dateTimeFormat as properties of the context parameter. These options are passed to a Intl.DateTimeFormat constructor.

Fixed

• [#877] Dynamic imports of react-dnd and related packages are now obfuscated to discourage bundlers like webpack from pre-processing those imports.