@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 --save react-querybuilder @react-querybuilder/dnd react-dnd react-dnd-html5-backend
# OR
yarn add react-querybuilder @react-querybuilder/dnd react-dnd react-dnd-html5-backend

Usage

To enable the drag-and-drop functionality of a query builder, wrap the <QueryBuilder /> element in <QueryBuilderDnD /> and pass in the exports from react-dnd and react-dnd-html5-backend as props to QueryBuilderDnD.

import { QueryBuilderDnD } from '@react-querybuilder/dnd';
import * as ReactDnD from 'react-dnd';
import * as ReactDndHtml5Backend from 'react-dnd-html5-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, ...ReactDndHtml5Backend }}>
      <QueryBuilder fields={fields} query={query} onQueryChange={q => setQuery(q)} />
    </QueryBuilderDnD>
  );
};

Notes

• While not strictly necessary, we strongly recommend passing the react-dnd and react-dnd-html5-backend exports in as props to <QueryBuilderDnD />. If they are not passed in as props, the initial render of the query builder will 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 the <QueryBuilder /> element.

• <QueryBuilderDnD /> does not need to be an immediate ancestor to <QueryBuilder />.

• Multiple <QueryBuilder />s may be nested beneath a single <QueryBuilderDnD />. The same drag-and-drop settings will be applied to each of them.

• 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 { DndProvider } from 'react-dnd';
  import { HTML5Backend } from 'react-dnd-html5-backend';
  import { QueryBuilder, RuleGroupType } from 'react-querybuilder';
  import { SomeOtherDndContextConsumer } from './SomeOtherDndContextConsumer';
  
  const fields = [
    { name: 'firstName', label: 'First Name' },
    { name: 'lastName', label: 'Last Name' },
  ];
  
  const ChildComponentOfDndProvider = () => {
    const [query, setQuery] = useState<RuleGroupType>({ combinator: 'and', rules: [] });
  
    return (
      <QueryBuilderDndWithoutProvider>
        <QueryBuilder fields={fields} query={query} onQueryChange={q => setQuery(q)} />
      </QueryBuilderDndWithoutProvider>
    );
  };
  
  const App = () => {
    return (
      <DndProvider backend={HTML5Backend}>
        <SomeOtherDndContextConsumer />
        <ChildComponentOfDndProvider />
      </DndProvider>
    );
  };
  

Changelog

[v6.0.0] - 2023-02-18

Changed

• [#455] A UMD build is no longer provided. See new instructions for buildless environments using ESM.
• [#431] Major ValueEditor update--including the ValueEditors in the compatibility packages--for "between"/"notBetween" operators. When the operator for a rule is "between" or "notBetween", two inputs will be displayed. Each will have the class "rule-value-list-item". They will manage the value as a comma-separated list unless listsAsArrays is true, in which case a proper array will be used.
• [#431] The default border radius on rule groups and branch lines (SCSS variable $rqb-border-radius) is now 0.25rem (previously 4px). Visually, this should be the same for most users since 16px is the default font-size on most browsers, and $16 \times 0.25 = 4$.
• [#431] Utility function c has been removed. Use a package like clsx (what RQB uses internally) instead.
• [#431] Bulma compatibility components no longer specify the is-small class, so they will be rendered at their default size.

Fixed

• [#452] All packages now use the "exports" field in their package.json for better ESM compatibility.

Added

• [#452] New ValueEditor prop selectorComponent (optional) enables the replacement of only the selector component in the value editor without recreating the logic in the default value editor. E.g., const MyValueEditor = (props: ValueEditorProps) => (<ValueEditor {...props} selectorComponent={MyValueSelector} />) will use the default value editor logic and presentation except when it would normally display the default ValueSelector.
• [#452] New React Native-compatible package @react-querybuilder/native and associated example showcasing multiple UI libraries.
• [#452] New exports:
  • useQueryBuilder: All logic and configuration formerly internal to the QueryBuilder component has been extracted into a custom Hook, making it easy to implement one's own presentation layer without reproducing or copy-pasting the official component code.
  • useRuleGroup: As useQueryBuilder is to the QueryBuilder component, the useRuleGroup Hook is to the RuleGroup component.
  • useRule: As useRuleGroup is to the RuleGroup component, the useRule Hook is to the Rule component.
  • RuleGroupHeaderComponents/RuleGroupBodyComponents: These JSX fragments have been extracted from the RuleGroup component and exposed as named exports, enabling the creation of a custom RuleGroup wrapper without recreating the "innards" of the default RuleGroup. (For example, the new @react-querybuilder/native package wraps these fragments in View elements from react-native).
• [#431] New props and Hook returns to support ValueEditors new behavior for "between"/"notBetween" operators.
  • New QueryBuilder prop getValueEditorSeparator: Takes a field name and an operator name and should return a ReactNode (string, element, etc.) that will be placed between the two editors when operator is "between" or "notBetween". E.g., getValueEditorSeparator={() => "and"}.
  • New QueryBuilder prop parseNumbers: When true, the default ValueEditor will update its rule with an actual number instead of the string representation whenever possible.
  • New ValueEditor prop skipHook: When true, the useValueEditor hook call within the default ValueEditor component will not make query updates. Enables safer rendering of the default ValueEditor as a fallback to a custom value editor.
  • The useValueEditor hook now returns an object with valueAsArray and multiValueHandler properties. See ValueEditor code for usage.
• [#455] regenerateIDs works for any object, not just rule groups.
• [#455] Query tools (add, remove, update, and move) will fail gracefully and return the original query if the provided path or parentPath points to an invalid location in the query hierarchy.
• [#463] The formatQuery option quoteFieldNamesWith now accepts an array of strings with two elements. The first element will precede each field name and the second will succeed each field name. E.g., ['[', ']'] would result in `[Field name] ...`.