Skip to main content
Version: v7 / v8

Drag-and-drop

The @react-querybuilder/dnd package augments React Query Builder with drag-and-drop functionality. Click here for demo.

Usage​

To enable drag-and-drop on a query builder, install react-dnd and either react-dnd-html5-backend or react-dnd-touch-backend (or both), then render the QueryBuilderDnD context provider higher in the component tree than QueryBuilder.

Note: The enableDragAndDrop prop doesn't need to be set directly on the QueryBuilder component unless it's explicitly false to override the implicit true value set by QueryBuilderDnD.

When the enableDragAndDrop prop is true, a drag handle appears on the left side of each rule and group header. Clicking and dragging the handle element allows users to visually reorder rules and groups.

npm i react-querybuilder @react-querybuilder/dnd react-dnd react-dnd-html5-backend react-dnd-touch-backend
import { QueryBuilderDnD } from '@react-querybuilder/dnd';
import * as ReactDnD from 'react-dnd';
import * as ReactDndHtml5Backend from 'react-dnd-html5-backend';
import * as ReactDndTouchBackend from 'react-dnd-touch-backend';
import { QueryBuilder } from 'react-querybuilder';

const App = () => (
  <QueryBuilderDnD dnd={{ ...ReactDnD, ...ReactDndHtml5Backend, ...ReactDndTouchBackend }}>
    <QueryBuilder />
  </QueryBuilderDnD>
);

Styling​

The default stylesheet applies special styles during drag-and-drop operations to help anticipate the result of the impending drop. For more information, see Styling overview § Drag-and-drop.

Cloning and grouping​

By default, a successful drag-and-drop action moves a rule or group to a new location within the query builder, but there are three alternative behaviors:

  • Clone: Hold down the Alt key (⌥ Option on macOS) before and during the drag to clone the dragged rule/group instead of moving it. The original object remains in place and the clone is inserted at the drop location.
  • Group: Hold down the Ctrl key before and during the drag to create a new group at the drop location. The new group's rules array contains the rule or group originally at the drop location and the dragged rule/group, in that order. (This operation is similar to how new folders are created on iOS by dragging one app icon on top of another.)
  • Clone into group: Hold down the Alt/⌥ Option and Ctrl keys before and during the drag to create a new group at the drop location and clone the dragged rule/group into the new group instead of moving it.

The keys that determine alternate behaviors are configurable. See copyModeModifierKey and groupModeModifierKey.

Existing drag-and-drop contexts​

If your application already uses react-dnd, use QueryBuilderDndWithoutProvider instead of QueryBuilderDnD. They are functionally equivalent, but the former assumes a <DndProvider /> already exists higher in the component tree. The latter renders its own DndProvider which conflicts with any pre-existing ones. (If you use the wrong component, you'll probably see the error message "Cannot have two HTML5 backends at the same time" in the console.)

Props​

The following props are accepted on the QueryBuilderDnD and QueryBuilderDndWithoutProvider components.

dnd​

typeof import('react-dnd') & { ReactDndBackend?: BackendFactory; HTML5Backend?: BackendFactory; TouchBackend?: BackendFactory; }

Provide this prop if you want the query builder to render immediately with drag-and-drop enabled. Otherwise, the component asynchronously loads react-dnd, react-dnd-html5-backend, and react-dnd-touch-backend. Drag-and-drop features are only enabled once those packages have loaded.

When both backends are provided, the touch backend is preferred when a touch device is detected.

canDrop​

(params: { dragging: RuleGroupTypeAny, hovering: RuleGroupTypeAny, groupItems?: boolean }) => boolean

This function determines whether a "drop" at the current hover location is valid during a drag operation. The dragging and hovering properties represent the dragged rule/group and the currently hovered rule/group, respectively. Each property includes the object's original path and qbId. groupItems is true if the groupModeModifierKey is currently pressed.

copyModeModifierKey​

string

Key code for the modifier key that puts a drag-and-drop action in "copy" mode. Default is "alt" (Alt on Windows and Linux, ⌥ Option on macOS).

groupModeModifierKey​

string

Key code for the modifier key that puts a drag-and-drop action in "group" mode. Default is "ctrl" (Ctrl).