Is it free? Does it need MUI X?

Yes, and no. The builder is MIT licensed and uses only @mui/material and @mui/icons-material (both MIT) with Emotion. No MUI X package or license is involved.

Do I need to use shadcn to install it?

Only the CLI, once: shadcn add copies the file into your project and installs the npm packages. It needs a components.json, which shadcn init creates; you do not have to use any shadcn/ui components afterwards.

Does it follow my MUI theme?

It wraps itself in its own ThemeProvider and picks light or dark from the dark class on , so it works without your theme or CssBaseline. To match your app, edit themeFor in the installed file, or remove the wrapper and let it inherit your theme.

Which MUI version is it built for?

This site runs it on @mui/material 9.5. It imports components by path (@mui/material/Autocomplete and so on), which keeps the bundle to what it uses.

Does it work with the Next.js App Router?

Yes. The builder is a client component. If you use MUI elsewhere on the page, keep your usual AppRouterCacheProvider from @mui/material-nextjs so Emotion's styles are collected on the server.

How do I get SQL or a MongoDB filter out of it?

The store holds the query as plain JSON. Encode it with a codec from @qnot/core/formats: sqlFormat({ dialect: "postgres", params: "numbered" }) gives SQL with bound parameters; mongo and jsonlogic give filters.

MUI query builder

A query builder made of Material UI components: TextField, Select, Autocomplete, ToggleButtonGroup. MIT, no MUI X license, one command to install as source.

Install All kits

MIT · Material UI · Emotion · React 18+

licenseMIT

needs@mui/material + Emotion

MUI XNot required

installOne shadcn add

The MUI builder that shadcn add installs, live on this page. Edit a rule and watch the exports.

Install it

One command copies the MUI builder and the kit-agnostic core it shares with the other kits into components/qnot, and installs @qnot/core and @qnot/react. MIT licensed.

pnpm dlx shadcn@latest add https://coss.com/qnot/r/query-builder-mui.json

Installs @mui/material, @mui/icons-material and Emotion. The builder wraps itself in its own ThemeProvider (light or dark from the dark class on <html>), so it needs neither your theme nor CssBaseline; edit themeFor in the file to match your app.

Source

4 files, exactly what installs

388 lines

// Part of qnot (https://github.com/cosscom/qnot). MIT licensed; installable with shadcn.
// qnot's query builder in Material UI: TextField, Select, Autocomplete, ToggleButtonGroup and
// Paper, themed to follow the page's light/dark mode, on @qnot/react's headless hooks. MIT licensed.
'use client';

import AccountTreeOutlined from '@mui/icons-material/AccountTreeOutlined';
import Add from '@mui/icons-material/Add';
import Close from '@mui/icons-material/Close';
import ContentCopy from '@mui/icons-material/ContentCopy';
import CreateNewFolderOutlined from '@mui/icons-material/CreateNewFolderOutlined';
import DragIndicator from '@mui/icons-material/DragIndicator';
import Functions from '@mui/icons-material/Functions';
import Lock from '@mui/icons-material/Lock';
import LockOpen from '@mui/icons-material/LockOpen';
import TextFields from '@mui/icons-material/TextFields';
import ViewColumnOutlined from '@mui/icons-material/ViewColumnOutlined';
import Autocomplete from '@mui/material/Autocomplete';
import Button from '@mui/material/Button';
import Chip from '@mui/material/Chip';
import CircularProgress from '@mui/material/CircularProgress';
import FormControlLabel from '@mui/material/FormControlLabel';
import IconButton from '@mui/material/IconButton';
import InputAdornment from '@mui/material/InputAdornment';
import ListSubheader from '@mui/material/ListSubheader';
import Menu from '@mui/material/Menu';
import MenuItem from '@mui/material/MenuItem';
import Paper from '@mui/material/Paper';
import Slider from '@mui/material/Slider';
import { createTheme, ThemeProvider, type Theme } from '@mui/material/styles';
import Switch from '@mui/material/Switch';
import TextField from '@mui/material/TextField';
import ToggleButton from '@mui/material/ToggleButton';
import ToggleButtonGroup from '@mui/material/ToggleButtonGroup';
import Tooltip from '@mui/material/Tooltip';
import Typography from '@mui/material/Typography';
import { useMemo, useState, useSyncExternalStore, type ComponentProps, type ReactNode } from 'react';
import { createQueryBuilder } from '@/components/qnot/kits/shared/builder';
import { useNumberDraft } from '@/components/qnot/kits/shared/draft';
import type { Item, Kit, Width } from '@/components/qnot/kits/shared/kit';

const WIDTH: Record<Width, string | number> = { auto: 'auto', full: '100%', xs: 104, sm: 152, md: 184, lg: 264 };
const width = (w: Width | undefined, fallback: Width) => ({ width: WIDTH[w ?? fallback], minWidth: w === 'auto' || (!w && fallback === 'auto') ? 120 : undefined });

/** Follows the page's `.dark` class (next-themes / the site's toggle). */
function useDarkClass(): boolean {
  return useSyncExternalStore(
    (fn) => {
      const mo = new MutationObserver(fn);
      mo.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] });
      return () => mo.disconnect();
    },
    () => document.documentElement.classList.contains('dark'),
    () => false,
  );
}

const themes = new Map<boolean, Theme>();
const themeFor = (dark: boolean) => {
  let t = themes.get(dark);
  if (!t) {
    t = createTheme({
      palette: { mode: dark ? 'dark' : 'light', ...(dark && { background: { paper: '#1c1c1f', default: '#141416' } }) },
      shape: { borderRadius: 8 },
      typography: { fontFamily: 'inherit', fontSize: 13 },
      components: {
        MuiButton: { defaultProps: { size: 'small', disableElevation: true }, styleOverrides: { root: { textTransform: 'none' } } },
        MuiToggleButton: { styleOverrides: { root: { textTransform: 'none', paddingBlock: 3, paddingInline: 10 } } },
        MuiTooltip: { defaultProps: { arrow: true, enterDelay: 300 } },
      },
    });
    themes.set(dark, t);
  }
  return t;
};

const groupOf = (items: readonly Item[]) => {
  const out = new Map<string | undefined, Item[]>();
  for (const i of items) out.set(i.group, [...(out.get(i.group) ?? []), i]);
  return [...out];
};

function MenuButton({ trigger, heading, items, value, onSelect, disabled }: ComponentProps<Kit['Menu']>) {
  const [anchor, setAnchor] = useState<HTMLElement | null>(null);
  return (
    <>
      {trigger.iconOnly ? (
        <IconButton size="small" aria-label={trigger.label} disabled={disabled} onClick={(e) => setAnchor(e.currentTarget)} sx={{ p: 0.5 }}>
          {trigger.icon}
        </IconButton>
      ) : (
        <Button variant="text" startIcon={trigger.icon} disabled={disabled} onClick={(e) => setAnchor(e.currentTarget)}>
          {trigger.label}
        </Button>
      )}
      <Menu anchorEl={anchor} open={!!anchor} onClose={() => setAnchor(null)} slotProps={{ list: { dense: true } }}>
        {heading && <ListSubheader sx={{ lineHeight: '32px' }}>{heading}</ListSubheader>}
        {items.map((i) => (
          <MenuItem
            key={i.value}
            selected={value === i.value}
            onClick={() => {
              onSelect(i.value);
              setAnchor(null);
            }}
          >
            {i.label}
          </MenuItem>
        ))}
      </Menu>
    </>
  );
}

const kit: Kit = {
  name: 'mui',
  Provider({ children }) {
    const dark = useDarkClass();
    return <ThemeProvider theme={themeFor(dark)}>{children}</ThemeProvider>;
  },

  Select({ items, value, onChange, disabled, invalid, placeholder, width: w, mono, label }) {
    const options: ReactNode[] = [];
    for (const [group, opts] of groupOf(items)) {
      if (group !== undefined) options.push(<ListSubheader key={`g:${group}`}>{group}</ListSubheader>);
      for (const i of opts)
        options.push(
          <MenuItem key={i.value} value={i.value} disabled={i.disabled} sx={{ pl: 2 + (i.depth ?? 0) * 1.5, fontFamily: mono ? 'ui-monospace, monospace' : undefined, fontSize: mono ? 12 : undefined }}>
            {i.label}
          </MenuItem>,
        );
    }
    return (
      <TextField
        select
        size="small"
        value={value ?? ''}
        error={invalid}
        disabled={disabled}
        sx={width(w, 'auto')}
        slotProps={{
          htmlInput: { 'aria-label': label },
          select: {
            displayEmpty: true,
            renderValue: (v) => (v === '' ? <span style={{ opacity: 0.6 }}>{placeholder}</span> : (items.find((i) => i.value === v)?.label ?? String(v))),
            MenuProps: { slotProps: { list: { dense: true } } },
            sx: mono ? { fontFamily: 'ui-monospace, monospace', fontSize: 12 } : undefined,
          },
        }}
        onChange={(e) => onChange(e.target.value)}
      >
        {options}
      </TextField>
    );
  },

  TextInput: ({ value, onChange, type = 'text', disabled, invalid, placeholder, width: w, label }) => (
    <TextField
      size="small"
      type={type}
      value={value}
      placeholder={placeholder}
      error={invalid}
      disabled={disabled}
      sx={width(w, 'md')}
      slotProps={{ htmlInput: { 'aria-label': label ?? placeholder } }}
      onChange={(e) => onChange(e.target.value)}
    />
  ),

  Textarea: ({ value, onChange, disabled, invalid, placeholder, width: w }) => (
    <TextField size="small" multiline minRows={2} value={value} placeholder={placeholder} error={invalid} disabled={disabled} sx={width(w, 'lg')} onChange={(e) => onChange(e.target.value)} />
  ),

  NumberInput({ value, onChange, min, max, step, disabled, invalid, placeholder, width: w, prefix, suffix, label }) {
    const { draft, onDraftChange } = useNumberDraft(value, onChange);
    return (
      <TextField
        size="small"
        type="number"
        value={draft}
        placeholder={placeholder}
        error={invalid}
        disabled={disabled}
        sx={width(w, 'sm')}
        slotProps={{
          htmlInput: { min, max, step, 'aria-label': label },
          input: {
            startAdornment: prefix ? <InputAdornment position="start">{prefix}</InputAdornment> : undefined,
            endAdornment: suffix ? <InputAdornment position="end">{suffix}</InputAdornment> : undefined,
          },
        }}
        onChange={(e) => onDraftChange(e.target.value)}
      />
    );
  },

  Slider: ({ value, min, max, step, onChange, disabled, label }) => (
    <span style={{ display: 'inline-flex', alignItems: 'center', gap: 14, width: 240, paddingInline: 6 }}>
      <Slider size="small" value={value} min={min} max={max} step={step} disabled={disabled} aria-label={label} valueLabelDisplay="auto" onChange={(_, v) => onChange(v as number)} />
      <Typography variant="body2" sx={{ width: 32, textAlign: 'end', fontVariantNumeric: 'tabular-nums' }}>
        {value}
      </Typography>
    </span>
  ),

  Switch: ({ checked, onChange, disabled, label }) => (
    <FormControlLabel sx={{ m: 0, gap: 0.5 }} control={<Switch size="small" checked={checked} disabled={disabled} onChange={(_, c) => onChange(c)} />} label={<Typography variant="body2">{label}</Typography>} />
  ),

  MultiSelect({ items, value, onChange, disabled, invalid, placeholder, width: w }) {
    const selected = useMemo(() => items.filter((i) => value.includes(i.value)), [items, value]);
    return (
      <Autocomplete
        multiple
        size="small"
        disableCloseOnSelect
        options={items as Item[]}
        value={selected}
        disabled={disabled}
        groupBy={items.some((i) => i.group) ? (i) => i.group ?? '' : undefined}
        getOptionLabel={(i) => i.label}
        getOptionDisabled={(i) => !!i.disabled}
        isOptionEqualToValue={(a, b) => a.value === b.value}
        renderOption={(props, i) => {
          const { key, ...rest } = props as typeof props & { key: string };
          return (
            <li key={key} {...rest} style={{ ...rest.style, paddingLeft: 16 + (i.depth ?? 0) * 14 }}>
              {i.label}
            </li>
          );
        }}
        onChange={(_, next) => onChange(next.map((i) => i.value))}
        sx={width(w, 'lg')}
        renderInput={(params) => <TextField {...params} error={invalid} placeholder={selected.length ? undefined : placeholder} />}
      />
    );
  },

  AsyncSelect({ multiple, items, loading, onQueryChange, value, onChange, disabled, invalid, placeholder, width: w, allowCustom }) {
    const common = {
      size: 'small' as const,
      options: items as Item[],
      loading,
      disabled,
      freeSolo: !!allowCustom,
      filterOptions: (x: Item[]) => x,
      getOptionLabel: (i: Item | string) => (typeof i === 'string' ? i : i.label),
      isOptionEqualToValue: (a: Item, b: Item | string) => a.value === (typeof b === 'string' ? b : b.value),
      onInputChange: (_: unknown, q: string, reason: string) => reason !== 'reset' && onQueryChange(q),
      sx: width(w, 'lg'),
      renderInput: (params: object) => (
        <TextField
          {...params}
          error={invalid}
          placeholder={placeholder}
          slotProps={{
            input: {
              ...(params as { InputProps?: object }).InputProps,
              endAdornment: (
                <>
                  {loading && <CircularProgress color="inherit" size={14} />}
                  {(params as { InputProps?: { endAdornment?: ReactNode } }).InputProps?.endAdornment}
                </>
              ),
            },
          }}
        />
      ),
    };
    const asItem = (v: Item | string): Item => (typeof v === 'string' ? { value: v, label: v, raw: v } : v);
    return multiple ? (
      <Autocomplete {...common} multiple disableCloseOnSelect value={value as Item[]} onChange={(_: unknown, next: (Item | string)[]) => onChange(next.map(asItem))} />
    ) : (
      <Autocomplete {...common} value={value[0] ?? null} onChange={(_: unknown, next: Item | string | null) => onChange(next ? [asItem(next)] : [])} />
    );
  },

  Button: ({ children, icon, onClick, disabled, variant = 'outline' }) => (
    <Button variant={variant === 'outline' ? 'outlined' : 'text'} startIcon={icon} disabled={disabled} onClick={onClick}>
      {children}
    </Button>
  ),

  IconButton: ({ label, icon, onClick, disabled, pressed }) => (
    <IconButton size="small" aria-label={label} aria-pressed={pressed} color={pressed ? 'warning' : 'default'} disabled={disabled} onClick={onClick}>
      {icon}
    </IconButton>
  ),

  Toggle: ({ pressed, onChange, disabled, label, children }) => (
    <ToggleButton size="small" value="on" aria-label={label} selected={pressed} disabled={disabled} color={pressed ? 'warning' : 'standard'} onChange={() => onChange(!pressed)}>
      {children}
    </ToggleButton>
  ),

  Segmented: ({ items, value, onChange, disabled, label, compact }) => (
    <ToggleButtonGroup size="small" exclusive color="primary" aria-label={label} value={value} disabled={disabled} onChange={(_, v) => v && onChange(v)}>
      {items.map((i) => (
        <Tooltip key={i.value} title={i.tooltip ?? ''} disableHoverListener={!i.tooltip}>
          <ToggleButton value={i.value} aria-label={i.ariaLabel} data-source={i.value} sx={compact ? { px: 0.75, '& svg': { fontSize: 18 } } : undefined}>
            {i.label}
          </ToggleButton>
        </Tooltip>
      ))}
    </ToggleButtonGroup>
  ),

  Tooltip: ({ label, children }) => (
    <Tooltip title={label}>
      <span style={{ display: 'inline-flex' }}>{children}</span>
    </Tooltip>
  ),

  Badge: ({ children }) => <Chip size="small" color="primary" variant="outlined" label={children} />,

  Menu: MenuButton,

  Surface: ({ kind, depth, negated, locked, dragging, drop, style, children, ...rest }) => (
    <Paper
      {...rest}
      variant="outlined"
      style={style}
      sx={{
        display: 'flex',
        flexDirection: 'column',
        gap: 1.5,
        p: 1.5,
        borderRadius: 3,
        bgcolor: depth % 2 === 0 ? 'action.hover' : 'background.paper',
        borderColor: negated ? 'warning.main' : kind === 'array' ? 'primary.light' : undefined,
        borderStyle: negated ? 'dashed' : 'solid',
        opacity: dragging ? 0.4 : locked ? 0.8 : 1,
        color: 'text.primary',
        // The drop indicator: a line centred in the 8px gap between siblings, with a dot at its start.
        ...((drop === 'before' || drop === 'after') && {
          position: 'relative',
          '&::before, &::after': { content: '""', position: 'absolute', pointerEvents: 'none' },
          '&::before': { left: 0, right: 0, height: 2, borderRadius: 1, bgcolor: 'primary.main', [drop === 'before' ? 'top' : 'bottom']: -5 },
          '&::after': { left: -4, width: 8, height: 8, borderRadius: '50%', border: 2, borderColor: 'primary.main', bgcolor: 'background.paper', [drop === 'before' ? 'top' : 'bottom']: -8 },
        }),
      }}
    >
      {children}
    </Paper>
  ),

  Empty: ({ children }) => (
    <Typography variant="body2" color="text.secondary" sx={{ border: 1, borderStyle: 'dashed', borderColor: 'divider', borderRadius: 2, py: 2, textAlign: 'center' }}>
      {children}
    </Typography>
  ),
  ErrorText: ({ children }) => (
    <Typography variant="caption" color="error" sx={{ pl: 3.5 }}>
      {children}
    </Typography>
  ),
  Muted: ({ children, mono }) => (
    <Typography variant="body2" color="text.secondary" component="span" sx={mono ? { fontFamily: 'ui-monospace, monospace' } : undefined}>
      {children}
    </Typography>
  ),
  FunctionFrame: ({ children, fn }) => (
    <Paper variant="outlined" data-function={fn} sx={{ display: 'inline-flex', flexWrap: 'wrap', alignItems: 'center', gap: 0.5, p: 0.5, pr: 1, borderStyle: 'dashed', bgcolor: 'action.hover' }}>
      {children}
    </Paper>
  ),

  icons: {
    grip: <DragIndicator fontSize="small" />,
    plus: <Add />,
    folderPlus: <CreateNewFolderOutlined />,
    list: <AccountTreeOutlined />,
    copy: <ContentCopy fontSize="small" />,
    remove: <Close fontSize="small" />,
    lock: <Lock fontSize="small" />,
    unlock: <LockOpen fontSize="small" />,
    fn: <Functions fontSize="small" />,
    value: <TextFields fontSize="small" />,
    field: <ViewColumnOutlined fontSize="small" />,
  },
};

/** The qnot query builder in Material UI. Same props as the coss builder. */
export const QueryBuilder = createQueryBuilder(kit);

/** The kit's primitives, for building variants or tests. */
export { kit as muiKit };

Use it.

Describe your fields, create a store, render the builder. The store's onChange hands you the query.

fields.ts

import { defineFields, f, type QueryOf } from '@qnot/core';

export const fields = defineFields({
  name: f.text(),
  age: f.number({ min: 0, max: 120, integer: true }),
  plan: f.enum(['free', 'pro', 'team', 'enterprise']),
  tags: f.multiEnum(['vip', 'beta', 'churn-risk', 'partner']),
  verified: f.boolean(),
  signedUp: f.date({ label: 'Signed up' }),
});

export const initial: QueryOf<typeof fields> = {
  kind: 'group',
  combinator: 'and',
  children: [
    { kind: 'rule', field: 'age', operator: 'gte', value: 21 },
    { kind: 'rule', field: 'plan', operator: 'in', value: ['pro', 'team'] },
    {
      kind: 'group',
      combinator: 'or',
      children: [
        { kind: 'rule', field: 'tags', operator: 'hasAny', value: ['vip'] },
        { kind: 'rule', field: 'signedUp', operator: 'gt', value: '2025-01-01' },
      ],
    },
  ],
};

Filters.tsx

'use client';
import type { QueryOf } from '@qnot/core';
import { useQueryStore } from '@qnot/react';
import { QueryBuilder } from '@/components/qnot/kits/mui';
import { fields, initial } from './fields';

export function Filters({ onChange }: { onChange: (query: QueryOf<typeof fields>) => void }) {
  // Every edit hands you the query as JSON typed by your fields: save it, or encode it to SQL.
  const store = useQueryStore({ fields, initial, onChange });
  return <QueryBuilder store={store} showLock />;
}

Pickers are MUI Selects and Autocompletes, values are TextFields, AND / OR is a ToggleButtonGroup, and the add menu is a Menu. All of it sits on @qnot/react's hooks, which own the state.

Read the query with the store's onChange, useQuery() or store.getQuery(), and encode it with any format.

What you get.

The kit is only the controls. Everything else comes from the qnot store underneath.

Questions people ask

Is it free? Does it need MUI X?: Yes, and no. The builder is MIT licensed and uses only @mui/material and @mui/icons-material (both MIT) with Emotion. No MUI X package or license is involved.
Do I need to use shadcn to install it?: Only the CLI, once: shadcn add copies the file into your project and installs the npm packages. It needs a components.json, which shadcn init creates; you do not have to use any shadcn/ui components afterwards.Install with shadcn
Does it follow my MUI theme?: It wraps itself in its own ThemeProvider and picks light or dark from the dark class on <html>, so it works without your theme or CssBaseline. To match your app, edit themeFor in the installed file, or remove the wrapper and let it inherit your theme.
Which MUI version is it built for?: This site runs it on @mui/material 9.5. It imports components by path (@mui/material/Autocomplete and so on), which keeps the bundle to what it uses.
Does it work with the Next.js App Router?: Yes. The builder is a client component. If you use MUI elsewhere on the page, keep your usual AppRouterCacheProvider from @mui/material-nextjs so Emotion's styles are collected on the server.
How do I get SQL or a MongoDB filter out of it?: The store holds the query as plain JSON. Encode it with a codec from @qnot/core/formats: sqlFormat({ dialect: "postgres", params: "numbered" }) gives SQL with bound parameters; mongo and jsonlogic give filters.Formats