QueryBuilder Component

Overview

The QueryBuilder component helps users build complex search queries using an intuitive UI. It allows selecting columns, operators, and values, and combines them with logical operators like AND or OR.

---

Features

• Interactive Query Builder: Create queries by selecting columns, operators, and values.
• Popover Interface: Advanced filters are managed in a simple popover UI.
• Customizable: Define columns and their valid operators.
• Fully Styleable: Every visual element — including the advanced-filter form, the help modal, validation tooltips, and the syntax-highlight overlay — can be styled via the sx slot map.
• Callback Support: Trigger a function when the query is applied.

---

Installation

Ensure you have Material-UI installed alongside the package:

# with pnpm
pnpm add query-builder-react @mui/material @mui/icons-material @emotion/react @emotion/styled

# or with npm
npm install query-builder-react @mui/material @mui/icons-material @emotion/react @emotion/styled

# or with yarn
yarn add query-builder-react @mui/material @mui/icons-material @emotion/react @emotion/styled

---

Usage

Example:

import React from "react";
import QueryBuilder from "query-builder-react";

const columnsOperator = {
  name: { operators: ["contains", "exclude", "==", "!="] },
  id: { operators: ["contains", "exclude", "==", "!="] },
  duration: { operators: ["<", "<=", ">", ">=", "==", "!="] },
  created_at: { operators: ["before", "after", "exact"] },
};

export default function App() {
  const handleApply = (queries) => {
    console.log("Generated Queries:", queries);
  };
  return (
    <QueryBuilder
      columnsOperator={columnsOperator}
      defaultOperators={["AND", "OR"]}
      relatedOperators={[
        "contains",
        "exclude",
        "!=",
        "==",
        "<",
        "<=",
        ">",
        ">=",
        "before",
        "after",
        "exact",
      ]}
      placeholder='e.g. name contains "John" AND duration > 30'
      handleApply={handleApply}
    />
  );
}

---

Props

Prop	Type	Default	Description
columnsOperator	object	{}	Defines columns and their valid operators.
defaultOperators	string[]	[]	Logical operators for combining queries (e.g., AND, OR).
relatedOperators	string[]	[]	List of valid operators for the query builder.
handleApply	function	undefined	Callback triggered with the generated query when applied.
placeholder	string	""	Placeholder text shown inside the query text box when empty. Forwarded to the inner QueryTextBox.
sx	object	{}	Style overrides for individual slots of the component. See Custom Styling.

---

Custom Styling

The QueryBuilder component is fully styleable from the outside through the sx prop. Instead of accepting a single style object, sx is a slot map: each key targets a specific part of the rendered tree, and its value is any valid MUI sx value (object, function, or array).

QueryBuilder Slots

Slot	Targets
root	The outer wrapper Box of the entire component.
textBoxContainer	The Box wrapping the QueryTextBox and the tune button.
textBox	A nested slot map forwarded to QueryTextBox. See Text Box Slots.
iconButton	The tune (settings) IconButton.
popover	The advanced-filters Popover (wrapper).
popoverPaper	The Paper element inside the Popover. Override responsive width / height caps here.
popoverContent	The inner Box inside the popover.
title	The "Query Builder" title Typography.
queryForm	A nested slot map forwarded to QueryForm. See Query Form Slots.

All slots are optional. Any slot you don't provide simply falls back to the component's default styling.

Text Box Slots

The free-text query builder (QueryTextBox) exposes its own slot map, which you can drive either through sx.textBox from QueryBuilder or directly via the sx prop when using QueryTextBox standalone.

Slot	Targets
root	The outer wrapper Box of QueryTextBox.
inputRow	The Box wrapping the OutlinedInput and the Apply Button.
inputWrapper	The relative-positioned wrapper that holds the highlight overlay + input.
highlightOverlay	The transparent Box that paints colored tokens behind the input.
input	The OutlinedInput field.
adornmentBox	The flex Box inside the input's end adornment (holds help icon, custom adornment, Apply button).
helpButton	The help (?) IconButton.
helpTooltip	The Tooltip wrapping the help icon.
applyButton	The Apply Button.
errorTooltip	The validation-error Tooltip shown for invalid queries. Override bgcolor, color, etc.
hintTooltip	The hint Tooltip shown for an empty input.
popper	The suggestions Popper.
suggestionsBox	The Box rendered inside the popper (border / background wrapper).
suggestionsList	The List of suggestions.
suggestionItem	Each ListItemButton inside the suggestions list.
suggestionText	The Typography displaying each suggestion's text.
tokenColors	Color overrides for syntax-highlighted tokens. See Token Highlighting.
tokenFontWeights	Font-weight overrides per token type. See Token Font Weights.
helpModal	A nested slot map forwarded to the help modal. See Help Modal Slots.

Token Highlighting

As the user types, QueryTextBox parses the input into typed tokens and paints each one in a distinct color through a transparent overlay. You can override any/all of the default colors via sx.textBox.tokenColors (or sx.tokenColors when using QueryTextBox directly). Any CSS color value is accepted ("red", "#1976d2", "rgb(...)", theme colors via callbacks, etc.).

Token Type	Default Color	When It's Used
column	#1976d2 (blue)	Token at a column position that matches one of the configured columns.
customColumn	#0288d1 (light blue)	Token at a column position that is not in the configured columns.
operator	#d32f2f (red)	Token at the operator slot that matches a known related operator.
unknownOperator	#9e9e9e (grey)	Token at the operator slot that does not match any known operator (yet).
logical	#7b1fa2 (purple)	The separator between queries — AND / OR.
value	inherit	The right-hand side value token.

<QueryBuilder
  columnsOperator={columnsOperator}
  defaultOperators={["AND", "OR"]}
  handleApply={handleApply}
  sx={{
    textBox: {
      tokenColors: {
        column: "#0d47a1",
        customColumn: "#00897b",
        operator: "#c2185b",
        logical: "#6a1b9a",
        value: "#212121",
      },
    },
  }}
/>

Token Font Weights

You can also tweak the per-token font weight via sx.textBox.tokenFontWeights (or sx.tokenFontWeights on QueryTextBox directly). Accepts any valid CSS font-weight value (number or keyword).

Token Type	Default Weight
column	400
customColumn	400
operator	600
unknownOperator	400
logical	600
value	400

<QueryBuilder
  sx={{
    textBox: {
      tokenFontWeights: {
        column: 700,
        operator: 500,
        logical: 800,
      },
    },
  }}
/>

Query Form Slots

The advanced-filter form (QueryForm) inside the popover exposes its own slot map via sx.queryForm.

Slot	Targets
root	The outer wrapper Box of the form.
header	The "Combine queries with: [AND/OR]" header Box.
headerLabel	The "Combine queries with:" label Typography.
globalOperatorSelect	The global AND/OR Select.
rowsStack	The Stack that holds the query rows.
row	Each individual query row Box (column / operator / value / delete).
columnSelect	The column Select in each row.
operatorSelect	The operator Select in each row.
valueInput	The value TextField in each row.
deleteButton	The delete (trash) IconButton for each row.
deleteTooltip	The Tooltip wrapping the delete button.
actions	The action-buttons row Box (holds "Add Query" + "Apply Filters").
addButton	The "Add Query" Button.
applyButton	The "Apply Filters" Button.

Help Modal Slots

The query-syntax help modal (opened from the ? icon inside QueryTextBox) exposes its own slot map via sx.textBox.helpModal (or sx.helpModal when using QueryTextBox directly).

Slot	Targets
dialog	The Dialog itself.
title	The DialogTitle ("How to Use the Query Search").
closeButton	The close (×) IconButton in the title.
content	The DialogContent.
sectionTitle	Each <h6> section heading inside the content.
body	Each paragraph Typography inside the content.
codeBlock	The grey-background code blocks (e.g. column operator value).
exampleBlock	Each individual example code block.
exampleLabel	The uppercase caption above each example.
list	Each <ul> inside the content (tips, syntax bullets, etc.).
listItem	Each <li> Typography.
chip	Each inline Chip (e.g. name, ==, "John Doe").
divider	Each section Divider.
warningText	The red "Cannot mix AND and OR" warning paragraph.
colorLegendItem	Each list item in the syntax-highlighting color legend.
colorSwatch	The colored circle (Box) next to each legend item.
actions	The DialogActions row.
gotItButton	The "Got it" Button.

Basic Example

<QueryBuilder
  columnsOperator={columnsOperator}
  defaultOperators={["AND", "OR"]}
  relatedOperators={["contains", "exclude"]}
  handleApply={handleApply}
  sx={{
    root: { width: "100%" },
    textBoxContainer: { marginBottom: "8px" },
    iconButton: { color: "primary.main" },
    popover: { padding: "24px" },
    popoverPaper: { borderRadius: 3, boxShadow: 6 },
    popoverContent: { minWidth: "400px" },
    title: { color: "secondary.main", fontWeight: 700 },
    textBox: {
      input: { backgroundColor: "background.default" },
      applyButton: { textTransform: "none" },
      suggestionsBox: { width: "360px" },
      suggestionItem: {
        "&:hover": { backgroundColor: "action.hover" },
      },
    },
    queryForm: {
      header: { mb: 3 },
      globalOperatorSelect: { minWidth: 160 },
      columnSelect: { bgcolor: "background.default" },
      applyButton: { textTransform: "none", bgcolor: "success.main" },
    },
  }}
/>

Theme-Aware Example

Because each slot accepts a normal MUI sx value, you can use theme tokens, breakpoints, and callbacks just like in any other MUI component:

<QueryBuilder
  columnsOperator={columnsOperator}
  defaultOperators={["AND", "OR"]}
  handleApply={handleApply}
  sx={{
    root: {
      p: 2,
      borderRadius: 2,
      bgcolor: "background.paper",
      boxShadow: 1,
    },
    textBoxContainer: {
      gap: 1,
      mb: { xs: 1, md: 2 },
    },
    iconButton: (theme) => ({
      color: theme.palette.primary.main,
      "&:hover": { color: theme.palette.primary.dark },
    }),
    popover: { mt: 1 },
    popoverPaper: {
      // Override the default responsive width caps
      width: { xs: "calc(100vw - 32px)", sm: 600, md: 800 },
    },
    popoverContent: { minWidth: 480 },
    title: { mb: 1, color: "text.secondary" },
    textBox: {
      input: (theme) => ({
        borderRadius: 1,
        "& fieldset": { borderColor: theme.palette.divider },
      }),
      applyButton: { ml: 1 },
      popper: { zIndex: 1500 },
      suggestionsBox: {
        borderRadius: 1,
        boxShadow: 3,
      },
      errorTooltip: { bgcolor: "warning.main", color: "warning.contrastText" },
      hintTooltip: { bgcolor: "primary.dark" },
      helpModal: {
        dialog: { "& .MuiDialog-paper": { borderRadius: 3 } },
        sectionTitle: { color: "primary.main" },
        codeBlock: { bgcolor: "grey.900", color: "common.white" },
        gotItButton: { textTransform: "none" },
      },
    },
    queryForm: {
      root: { p: 3 },
      row: (theme) => ({
        bgcolor: theme.palette.action.hover,
        borderRadius: 1,
        p: 1,
      }),
      deleteButton: { "&:hover": { bgcolor: "error.light" } },
    },
  }}
/>

---

How It Works

Query Text Box: Shows the current query as it's built. Popover (Tune Icon): Opens an interface for detailed filter setup. Apply: The handleApply function is triggered with the final query when users apply their filters.

---

Notes

Required Props: columnsOperator and handleApply are essential for the component to work effectively. Custom Operators: Add or modify operators in columnsOperator or relatedOperators to suit your needs.

---

License

MIT