react-querybuilder-lite

A lightweight, headless React query builder with drag-and-drop support. Build complex filter UIs with any design system — zero styling opinions.

Why This Library?

Most query builders ship with opinionated styles or are tightly coupled to specific UI libraries. This library provides:

• Complete UI freedom — Use MUI, Chakra, Ant Design, Tailwind, or vanilla HTML
• Inversion of control — You own the markup, we handle the logic
• Type safety — Full TypeScript inference for queries, operators, and fields
• Lightweight — ~18KB minified + gzipped, including drag-and-drop support

Features

Feature	Description
Headless	No styles, no markup — bring your own components
Compound Components	Clean <QueryBuilder.Builder> composition API
Render Props	Full control via renderRule and renderGroup
Drag & Drop	Optional reordering via dnd-kit integration
Immutable Updates	Predictable state with structural sharing
Type Inference	Operators auto-filter based on field type
Nested Groups	Recursive AND/OR groups with maxDepth control
Lock Protection	Prevent modification of locked rules/groups
Slot Actions	Pre-wired handlers for add, remove, clone, lock

Installation

npm install react-querybuilder-lite

yarn add react-querybuilder-lite

pnpm add react-querybuilder-lite

Peer Dependencies: React 16.8+

Quick Start

import { useState } from 'react';
import { QueryBuilder, type Query } from 'react-querybuilder-lite';

const fields = [
  { label: 'Name', value: 'name', type: 'string' },
  { label: 'Age', value: 'age', type: 'number' },
];

const initialQuery: Query = {
  id: 'root',
  combinator: 'and',
  rules: [],
};

function App() {
  const [query, setQuery] = useState<Query>(initialQuery);

  return (
    <QueryBuilder value={query} onChange={setQuery} maxDepth={3}>
      <QueryBuilder.Builder
        fields={fields}
        renderRule={({ rule, fields, operators, onChange, slots }) => (
          <div className="rule">
            <select
              value={rule.field}
              onChange={(e) => onChange({ field: e.target.value })}
            >
              <option value="">Select field</option>
              {fields.map((f) => (
                <option key={f.value} value={f.value}>{f.label}</option>
              ))}
            </select>

            <select
              value={rule.operator}
              onChange={(e) => onChange({ operator: e.target.value })}
            >
              {operators.map((op) => (
                <option key={op.value} value={op.value}>{op.name}</option>
              ))}
            </select>

            <input
              value={rule.value ?? ''}
              onChange={(e) => onChange({ value: e.target.value })}
            />

            <button onClick={slots.onRemove}>Remove</button>
          </div>
        )}
        renderGroup={({ group, children, onChange, slots }) => (
          <div className="group">
            <select
              value={group.combinator}
              onChange={(e) => onChange({ combinator: e.target.value })}
            >
              <option value="and">AND</option>
              <option value="or">OR</option>
            </select>

            <button onClick={slots.onAddRule}>+ Rule</button>
            <button onClick={slots.onAddGroup}>+ Group</button>

            <div className="rules">{children}</div>
          </div>
        )}
      />
    </QueryBuilder>
  );
}

With Drag & Drop

Use QueryBuilder.BuilderWithDnD to enable drag-and-drop reordering.

import { QueryBuilder, type Query } from 'react-querybuilder-lite';

<QueryBuilder value={query} onChange={setQuery}>
  <QueryBuilder.BuilderWithDnD
    fields={fields}
    renderRule={({ rule, fields, operators, onChange, slots }) => (
      <div className="rule">
        {/* Drag handle - spread slots.dragHandles on any element */}
        <span className="drag-handle" {...slots.dragHandles}>⠿</span>

        <select value={rule.field} onChange={(e) => onChange({ field: e.target.value })}>
          {fields.map((f) => <option key={f.value} value={f.value}>{f.label}</option>)}
        </select>

        {/* ... rest of your UI */}
      </div>
    )}
    renderGroup={({ group, children, onChange, slots }) => (
      <div className="group">
        <span className="drag-handle" {...slots.dragHandles}>⠿</span>

        <select value={group.combinator} onChange={(e) => onChange({ combinator: e.target.value })}>
          <option value="and">AND</option>
          <option value="or">OR</option>
        </select>

        <button onClick={slots.onAddRule}>+ Rule</button>
        <button onClick={slots.onAddGroup}>+ Group</button>

        {children}
      </div>
    )}
  />
</QueryBuilder>

API Reference

<QueryBuilder>

Root component that provides state management context.

Prop	Type	Required	Description
value	Query	Yes	The query state
onChange	(query: Query) => void	Yes	Called when query changes
maxDepth	number	No	Maximum nesting depth. 1 = no nesting, 2 = one level, etc.
children	ReactNode	Yes	Must contain Builder or BuilderWithDnD

<QueryBuilder.Builder>

Renders the query tree without drag-and-drop.

Prop	Type	Required	Description
fields	Field[]	Yes	Available fields for rules
renderRule	(props: RuleRenderProps) => ReactNode	Yes	Render function for rules
renderGroup	(props: GroupRenderProps) => ReactNode	Yes	Render function for groups
operatorsByFieldType	Record<FieldType, Operator[]>	No	Custom operator mapping

<QueryBuilder.BuilderWithDnD>

Same props as Builder, plus optional drag preview customization.

Prop	Type	Required	Description
renderDragPreview	(props: DragPreviewProps) => ReactNode	No	Custom drag overlay

Render Props

RuleRenderProps

interface RuleRenderProps {
  rule: Rule;                    // Current rule data
  path: number[];                // Position in tree (e.g., [0, 1])
  depth: number;                 // Nesting level
  fields: Field[];               // Available fields
  operators: Operator[];         // Operators for selected field type
  selectedField?: Field;         // Currently selected field
  selectedOperator?: Operator;   // Currently selected operator
  slots: {
    onRemove: () => void;        // Remove this rule
    onClone: () => void;         // Duplicate this rule
    onToggleLock: () => void;    // Toggle lock state
    dragHandles: DragHandleType; // Spread on drag handle element
  };
  onChange: (updates: Partial<Rule>) => void;  // Update rule
}

GroupRenderProps

interface GroupRenderProps {
  group: RuleGroup;              // Current group data
  path: number[];                // Position in tree
  depth: number;                 // Nesting level
  children: ReactNode;           // Rendered child rules/groups
  slots: {
    onAddRule: () => void;       // Add rule to this group
    onAddGroup: () => void;      // Add nested group
    onRemove: () => void;        // Remove this group
    onClone: () => void;         // Duplicate this group
    onToggleLock: () => void;    // Toggle lock state
    dragHandles: DragHandleType; // Spread on drag handle element
  };
  onChange: (updates: Partial<RuleGroup>) => void;  // Update group
}

Terminology

Term	Description
Field (or Column)	The data attribute you want to filter on. For example, "First Name", "Age", "Created Date" are fields.
Operator	The comparison operation like "equals", "contains", "greater than".
Field Type	Category of the field that determines available operators. Default types: string, number, boolean, date. You can define custom types.
Combinator	Logical operator to combine rules: AND or OR.

Types

Core Types

// The root query structure
type Query = RuleGroup;

interface RuleGroup {
  id: string;
  combinator: 'and' | 'or';
  rules: Array<Rule | RuleGroup>;
  isLocked?: boolean;
}

interface Rule {
  id: string;
  field: string;
  operator: OperatorKey;
  value?: Value;
  isLocked?: boolean;
}

interface Field {
  label: string;
  value: string;
  type: string;  // 'string' | 'number' | 'boolean' | 'date' or any custom type
}

Operators

Built-in operators organized by type:

Type	Operators
Unary	is_empty, is_not_empty, is_true, is_false
Binary	equal, not_equal, less, less_or_equal, greater, greater_or_equal, contains, starts_with, ends_with
Range	between, not_between
List	in, not_in

Operators are automatically filtered by field type:

Field Type	Available Operators
string	is_empty, is_not_empty, equal, not_equal, contains, starts_with, ends_with, in, not_in
number	is_empty, is_not_empty, equal, not_equal, less, less_or_equal, greater, greater_or_equal, between, not_between, in, not_in
boolean	is_empty, is_not_empty, is_true, is_false
date	is_empty, is_not_empty, equal, not_equal, less, greater, between, not_between, in, not_in

Custom Field Types

You're not limited to the default field types. Define your own types with custom operators:

import { QueryBuilder, type Query, type Operator } from 'react-querybuilder-lite';

// Define fields with custom types
const fields = [
  { label: 'Name', value: 'name', type: 'string' },
  { label: 'Email', value: 'email', type: 'email' },           // Custom type
  { label: 'Created', value: 'createdAt', type: 'datetime' },  // Custom type
  { label: 'Price', value: 'price', type: 'currency' },        // Custom type
];

// Provide operators for your custom types
const operatorsByFieldType: Record<string, Operator[]> = {
  string: [
    { name: 'Equals', value: 'equal', type: 'binary' },
    { name: 'Contains', value: 'contains', type: 'binary' },
  ],
  email: [
    { name: 'Is', value: 'equal', type: 'binary' },
    { name: 'Contains', value: 'contains', type: 'binary' },
    { name: 'Ends With', value: 'ends_with', type: 'binary' },
  ],
  datetime: [
    { name: 'Before', value: 'less', type: 'binary' },
    { name: 'After', value: 'greater', type: 'binary' },
    { name: 'Between', value: 'between', type: 'range' },
  ],
  currency: [
    { name: 'Equals', value: 'equal', type: 'binary' },
    { name: 'Greater Than', value: 'greater', type: 'binary' },
    { name: 'Less Than', value: 'less', type: 'binary' },
    { name: 'Between', value: 'between', type: 'range' },
  ],
};

<QueryBuilder value={query} onChange={setQuery}>
  <QueryBuilder.Builder
    fields={fields}
    operatorsByFieldType={operatorsByFieldType}
    renderRule={...}
    renderGroup={...}
  />
</QueryBuilder>

Localization (i18n)

Full internationalization support. You control all user-facing text:

• fields — Translated field labels
• operatorsByFieldType — Translated operator names
• renderRule / renderGroup — Your components, your language. Full control over buttons, placeholders, and combinators
• dragDropAccessibility — Translated screen reader announcements

See the Localization story in Storybook → for examples in Spanish, Japanese, and French. Need another language? Easy to configure refer to the comprehensive documentation in the story.

Live Demos

📚 View Storybook →

Interactive examples showcasing all components with different configurations.

Design Decisions

Decision	Rationale
Headless architecture	Maximum flexibility, framework agnostic
Compound components	Implicit state sharing without prop drilling
Path-based operations	O(depth) updates with structural sharing
Render props over slots	Full control vs. limited customization
Cascading lock state	UX: locked parent = locked children
Optional DnD entry point	Respects bundle budgets

Contributing

Contributions are welcome! Please open an issue or submit a PR.

License

MIT