headless-react-query-builder

A composable, headless React 19 query builder component for conditional logic UIs.

Build complex nested conditions with AND, OR, and GROUP operations. The output is a structured JSON tree — plug it into alert managers, trading bots, IFTTT-style automations, pipeline managers, or anything that needs user-defined rules.

Live Storybook Demo

Features

Composition-first API — hooks as the primary interface, compound components for convenience, pre-built templates for zero setup
Headless by default — bring your own markup, or use a template preset
Tailwind CSS default styling with Bootstrap and unstyled alternatives
Controlled & uncontrolled — works both ways, just like a native input
TypeScript — fully typed, all types exported
Recursive nesting — groups within groups, unlimited depth
Framework-agnostic output — plain JSON, no vendor lock-in

Installation

npm install headless-react-query-builder

Peer dependencies:

npm install react@^19.0.0 react-dom@^19.0.0

Quick Start

Hooks (full control)

The primary API. You call hooks, you render whatever you want.

import { useQueryBuilder } from 'headless-react-query-builder';

function MyQueryBuilder() {
  const { query, addRule, addGroup, removeRule, updateRule, setCombinator } =
    useQueryBuilder();

  return (
    <div>
      <select
        value={query.combinator}
        onChange={(e) => setCombinator(query.id, e.target.value as 'AND' | 'OR')}
      >
        <option value="AND">AND</option>
        <option value="OR">OR</option>
      </select>

      {query.rules.map((rule) => {
        if ('combinator' in rule) {
          return <div key={rule.id}>Nested group: {rule.combinator}</div>;
        }
        return (
          <div key={rule.id}>
            <input
              value={rule.field}
              onChange={(e) => updateRule(rule.id, { field: e.target.value })}
              placeholder="Field"
            />
            <input
              value={String(rule.value)}
              onChange={(e) => updateRule(rule.id, { value: e.target.value })}
              placeholder="Value"
            />
            <button onClick={() => removeRule(rule.id)}>Remove</button>
          </div>
        );
      })}

      <button onClick={() => addRule(query.id)}>+ Rule</button>
      <button onClick={() => addGroup(query.id)}>+ Group</button>
    </div>
  );
}

Component wrapper (with context)

Wraps useQueryBuilder in a provider so child components can access the query state via context.

import { useState } from 'react';
import { QueryBuilder, createEmptyGroup } from 'headless-react-query-builder';
import type { Group } from 'headless-react-query-builder';

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

  return (
    <QueryBuilder value={query} onChange={setQuery}>
      {/* Child components can use useQueryBuilderContext() */}
      <pre>{JSON.stringify(query, null, 2)}</pre>
    </QueryBuilder>
  );
}

Form submission

Pass a name prop to render a hidden input with the serialized JSON:

<form onSubmit={handleSubmit}>
  <QueryBuilder name="query" defaultValue={initialQuery}>
    {/* ... */}
  </QueryBuilder>
  <button type="submit">Save</button>
</form>

The hidden input value will be the JSON string of the current query state.

Data Model

The query is a recursive tree of rules and groups:

type Rule = {
  id: string;
  field: string;
  operator: string;
  value: unknown;
};

type Group = {
  id: string;
  combinator: 'AND' | 'OR';
  rules: (Rule | Group)[];
};

Example output:

{
  "id": "qb-1",
  "combinator": "AND",
  "rules": [
    { "id": "qb-2", "field": "temperature", "operator": "gt", "value": 100 },
    { "id": "qb-3", "field": "status", "operator": "eq", "value": "critical" },
    {
      "id": "qb-4",
      "combinator": "OR",
      "rules": [
        { "id": "qb-5", "field": "region", "operator": "eq", "value": "us-east" },
        { "id": "qb-6", "field": "region", "operator": "eq", "value": "eu-west" }
      ]
    }
  ]
}

API Reference

`useQueryBuilder(options?)`

The primary hook. Returns the query state and all mutation functions.

Options:

Option	Type	Description
`value`	`Group`	Controlled query value
`defaultValue`	`Group`	Initial value for uncontrolled usage
`onChange`	`(query: Group) => void`	Called on every change
`fields`	`FieldDefinition[]`	Available fields for rules
`operators`	`OperatorDefinition[]`	Available operators (defaults provided)

Returns:

Property	Type	Description
`query`	`Group`	Current query state
`fields`	`FieldDefinition[]`	Available fields
`operators`	`OperatorDefinition[]`	Available operators
`addRule`	`(groupId: string) => void`	Add a rule to a group
`addGroup`	`(groupId: string) => void`	Add a nested group
`removeRule`	`(ruleId: string) => void`	Remove a rule
`removeGroup`	`(groupId: string) => void`	Remove a group
`updateRule`	`(ruleId: string, updates: Partial<Rule>) => void`	Update a rule's field, operator, or value
`setCombinator`	`(groupId: string, combinator: 'AND' \| 'OR') => void`	Change a group's combinator

`<QueryBuilder>`

Component wrapper that creates a context provider.

Prop	Type	Description
`value`	`Group`	Controlled value
`defaultValue`	`Group`	Initial value (uncontrolled)
`onChange`	`(query: Group) => void`	Change callback
`name`	`string`	Hidden input name for form submission
`fields`	`FieldDefinition[]`	Available fields
`operators`	`OperatorDefinition[]`	Available operators
`className`	`string`	CSS class for the root element
`children`	`ReactNode`	Child components

`useQueryBuilderContext()`

Access the query builder state from any child of <QueryBuilder>. Returns the same shape as useQueryBuilder.

Utilities

Export	Description
`createEmptyRule()`	Create a new rule with a generated ID
`createEmptyGroup(combinator?)`	Create a new group (defaults to `'AND'`)
`generateId()`	Generate a unique ID
`isGroup(item)`	Type guard — check if a rule-or-group is a `Group`
`DEFAULT_OPERATORS`	Built-in operator list (`=`, `!=`, `>`, `>=`, `<`, `<=`, `contains`, `not contains`, `between`, `in`, `not in`)

Defining Fields

import type { FieldDefinition } from 'headless-react-query-builder';

const fields: FieldDefinition[] = [
  { name: 'temperature', label: 'Temperature', type: 'number' },
  { name: 'status', label: 'Status', type: 'select', options: [
    { label: 'Active', value: 'active' },
    { label: 'Inactive', value: 'inactive' },
  ]},
  { name: 'created_at', label: 'Created At', type: 'date' },
  { name: 'name', label: 'Name', type: 'text' },
];

Supported field types: text, number, date, boolean, select.

Custom Operators

import type { OperatorDefinition } from 'headless-react-query-builder';

const operators: OperatorDefinition[] = [
  { name: 'eq', label: 'equals' },
  { name: 'gt', label: 'greater than' },
  { name: 'lt', label: 'less than' },
  { name: 'crosses_above', label: 'crosses above' },
  { name: 'crosses_below', label: 'crosses below' },
];

Templates

The library ships with template presets for common CSS frameworks:

// Tailwind (default)
import { TailwindQueryBuilder } from 'headless-react-query-builder/templates/tailwind';

// Bootstrap
import { BootstrapQueryBuilder } from 'headless-react-query-builder/templates/bootstrap';

// Unstyled (headless, no classes)
import { UnstyledQueryBuilder } from 'headless-react-query-builder/templates/unstyled';

Templates are built on top of the same hooks and context — they're just pre-styled component trees. You can use them as-is or as a reference for building your own.

Custom Button Labels

All templates accept a labels prop via the TemplateLabels type to customize button and combinator text:

import type { TemplateLabels } from 'headless-react-query-builder';

const labels: TemplateLabels = {
  addRule: '+ Condition',
  addGroup: '+ Sub-group',
  removeRule: 'Delete',
  removeGroup: 'Delete Group',
  and: 'ALL',
  or: 'ANY',
};

<TailwindQueryBuilder fields={fields} labels={labels} onChange={handleChange} />

All label fields are optional and fall back to sensible defaults (+ Rule, + Group, Remove, AND, OR).

Use Cases

All use cases are available as interactive Storybook stories across all three templates (Tailwind, Bootstrap, Unstyled). Each includes a complex preset showing a realistic initial query.

Alert Manager

Define when alerts fire based on metric thresholds.

import { TailwindQueryBuilder } from 'headless-react-query-builder/templates/tailwind';

const fields = [
  { name: 'cpu_usage', label: 'CPU Usage (%)', type: 'number' as const },
  { name: 'memory_usage', label: 'Memory Usage (%)', type: 'number' as const },
  { name: 'error_rate', label: 'Error Rate', type: 'number' as const },
  { name: 'response_time', label: 'Response Time (ms)', type: 'number' as const },
  { name: 'service', label: 'Service', type: 'select' as const, options: [
    { label: 'API', value: 'api' },
    { label: 'Worker', value: 'worker' },
    { label: 'Database', value: 'db' },
    { label: 'Cache', value: 'cache' },
  ]},
  { name: 'region', label: 'Region', type: 'select' as const, options: [
    { label: 'US East', value: 'us-east' },
    { label: 'US West', value: 'us-west' },
    { label: 'EU West', value: 'eu-west' },
  ]},
  { name: 'is_production', label: 'Is Production', type: 'boolean' as const },
];

<TailwindQueryBuilder fields={fields} onChange={saveAlertCondition} />

Algorithmic Trading

Build entry/exit conditions for trading strategies.

import { TailwindQueryBuilder } from 'headless-react-query-builder/templates/tailwind';

const fields = [
  { name: 'price', label: 'Price', type: 'number' as const },
  { name: 'rsi', label: 'RSI (14)', type: 'number' as const },
  { name: 'volume', label: 'Volume', type: 'number' as const },
  { name: 'sma_20', label: 'SMA (20)', type: 'number' as const },
  { name: 'ema_50', label: 'EMA (50)', type: 'number' as const },
  { name: 'macd', label: 'MACD', type: 'number' as const },
  { name: 'market', label: 'Market', type: 'select' as const, options: [
    { label: 'BTC/USD', value: 'btc-usd' },
    { label: 'ETH/USD', value: 'eth-usd' },
    { label: 'SOL/USD', value: 'sol-usd' },
    { label: 'AAPL', value: 'aapl' },
  ]},
];

const operators = [
  { name: 'gt', label: '>' },
  { name: 'lt', label: '<' },
  { name: 'gte', label: '>=' },
  { name: 'lte', label: '<=' },
  { name: 'eq', label: '=' },
  { name: 'crosses_above', label: 'crosses above' },
  { name: 'crosses_below', label: 'crosses below' },
];

<TailwindQueryBuilder fields={fields} operators={operators} onChange={updateStrategy} />

IFTTT / Automation

Compose "if this then that" trigger conditions.

const fields = [
  { name: 'trigger', label: 'Trigger', type: 'select' as const, options: [
    { label: 'Email received', value: 'email_received' },
    { label: 'File uploaded', value: 'file_uploaded' },
    { label: 'Webhook fired', value: 'webhook' },
    { label: 'Schedule', value: 'schedule' },
  ]},
  { name: 'sender', label: 'Sender', type: 'text' as const },
  { name: 'file_type', label: 'File Type', type: 'text' as const },
  { name: 'priority', label: 'Priority', type: 'select' as const, options: [
    { label: 'High', value: 'high' },
    { label: 'Medium', value: 'medium' },
    { label: 'Low', value: 'low' },
  ]},
  { name: 'is_recurring', label: 'Is Recurring', type: 'boolean' as const },
];

Pipeline Manager

Define branching logic and conditional steps in CI/CD pipelines.

const fields = [
  { name: 'branch', label: 'Branch', type: 'text' as const },
  { name: 'env', label: 'Environment', type: 'select' as const, options: [
    { label: 'Production', value: 'prod' },
    { label: 'Staging', value: 'staging' },
    { label: 'Development', value: 'dev' },
  ]},
  { name: 'test_coverage', label: 'Test Coverage (%)', type: 'number' as const },
  { name: 'has_migrations', label: 'Has Migrations', type: 'boolean' as const },
  { name: 'label', label: 'PR Label', type: 'select' as const, options: [
    { label: 'hotfix', value: 'hotfix' },
    { label: 'feature', value: 'feature' },
    { label: 'chore', value: 'chore' },
  ]},
];

Email Filtering

Build rules for sorting, labeling, or forwarding emails.

const fields = [
  { name: 'from', label: 'From', type: 'text' as const },
  { name: 'to', label: 'To', type: 'text' as const },
  { name: 'subject', label: 'Subject', type: 'text' as const },
  { name: 'has_attachment', label: 'Has Attachment', type: 'boolean' as const },
  { name: 'category', label: 'Category', type: 'select' as const, options: [
    { label: 'Primary', value: 'primary' },
    { label: 'Social', value: 'social' },
    { label: 'Promotions', value: 'promotions' },
    { label: 'Spam', value: 'spam' },
  ]},
  { name: 'size_kb', label: 'Size (KB)', type: 'number' as const },
];

Data Validation

Define validation rules for form fields or data imports.

const fields = [
  { name: 'field_name', label: 'Field Name', type: 'select' as const, options: [
    { label: 'Email', value: 'email' },
    { label: 'Phone', value: 'phone' },
    { label: 'Age', value: 'age' },
    { label: 'Username', value: 'username' },
  ]},
  { name: 'value_length', label: 'Value Length', type: 'number' as const },
  { name: 'is_required', label: 'Is Required', type: 'boolean' as const },
  { name: 'format', label: 'Format', type: 'select' as const, options: [
    { label: 'Email', value: 'email' },
    { label: 'URL', value: 'url' },
    { label: 'Phone', value: 'phone' },
    { label: 'Numeric', value: 'numeric' },
  ]},
  { name: 'min_value', label: 'Min Value', type: 'number' as const },
  { name: 'max_value', label: 'Max Value', type: 'number' as const },
];

Access Control

Define permission rules for role-based access.

const fields = [
  { name: 'role', label: 'Role', type: 'select' as const, options: [
    { label: 'Admin', value: 'admin' },
    { label: 'Editor', value: 'editor' },
    { label: 'Viewer', value: 'viewer' },
    { label: 'Guest', value: 'guest' },
  ]},
  { name: 'resource', label: 'Resource', type: 'select' as const, options: [
    { label: 'Dashboard', value: 'dashboard' },
    { label: 'Users', value: 'users' },
    { label: 'Settings', value: 'settings' },
    { label: 'Billing', value: 'billing' },
  ]},
  { name: 'action', label: 'Action', type: 'select' as const, options: [
    { label: 'Read', value: 'read' },
    { label: 'Write', value: 'write' },
    { label: 'Delete', value: 'delete' },
  ]},
  { name: 'is_2fa_enabled', label: '2FA Enabled', type: 'boolean' as const },
];

Search / Content Filtering

Build advanced search queries for content or products.

const fields = [
  { name: 'title', label: 'Title', type: 'text' as const },
  { name: 'author', label: 'Author', type: 'text' as const },
  { name: 'category', label: 'Category', type: 'select' as const, options: [
    { label: 'Technology', value: 'tech' },
    { label: 'Science', value: 'science' },
    { label: 'Business', value: 'business' },
    { label: 'Design', value: 'design' },
  ]},
  { name: 'published_date', label: 'Published Date', type: 'date' as const },
  { name: 'rating', label: 'Rating', type: 'number' as const },
  { name: 'is_featured', label: 'Is Featured', type: 'boolean' as const },
  { name: 'price', label: 'Price', type: 'number' as const },
];

## Development

```bash
# Install dependencies
npm install

# Start Storybook dev server
npm run dev

# Build the library
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint
npm run lint

# Build Storybook for deployment
npm run build-storybook

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
.github/workflows		.github/workflows
.storybook		.storybook
docs/plans		docs/plans
src		src
stories		stories
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md
codecov.yml		codecov.yml
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts
vitest.config.ts		vitest.config.ts
vitest.shims.d.ts		vitest.shims.d.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

headless-react-query-builder

Features

Installation

Quick Start

Hooks (full control)

Component wrapper (with context)

Form submission

Data Model

API Reference

`useQueryBuilder(options?)`

`<QueryBuilder>`

`useQueryBuilderContext()`

Utilities

Defining Fields

Custom Operators

Templates

Custom Button Labels

Use Cases

Alert Manager

Algorithmic Trading

IFTTT / Automation

Pipeline Manager

Email Filtering

Data Validation

Access Control

Search / Content Filtering

License

About

Uh oh!

Releases 2

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

headless-react-query-builder

Features

Installation

Quick Start

Hooks (full control)

Component wrapper (with context)

Form submission

Data Model

API Reference

useQueryBuilder(options?)

<QueryBuilder>

useQueryBuilderContext()

Utilities

Defining Fields

Custom Operators

Templates

Custom Button Labels

Use Cases

Alert Manager

Algorithmic Trading

IFTTT / Automation

Pipeline Manager

Email Filtering

Data Validation

Access Control

Search / Content Filtering

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`useQueryBuilder(options?)`

`<QueryBuilder>`

`useQueryBuilderContext()`

Packages