# Query Builder
URL: /docs/web/components/query-builder

Query Builder component.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import { QueryBuilderDocyrus } from '@docyrus/ui/components/query-builder';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { PropControls } from '@/components/prop-controls';
import { useDemoData } from '@/data/query-builder-data';

export function QueryBuilderDemo() {
  type Variant = 'default' | 'bordered' | 'compact' | 'striped';
  const [variant, setVariant] = useState
                  
                    
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Size</span>
                
                  
                    
                    
                  
                
              </div>
              
            </div>
          </div>
        </div>
      </div>
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-query-builder
```

**Dependencies:**
- [@react-querybuilder/dnd](https://www.npmjs.com/package/@react-querybuilder/dnd)
- [@atlaskit/pragmatic-drag-and-drop](https://www.npmjs.com/package/@atlaskit/pragmatic-drag-and-drop)
- [@dnd-kit/core](https://www.npmjs.com/package/@dnd-kit/core)
- [react-dnd](https://www.npmjs.com/package/react-dnd)
- [react-dnd-html5-backend](https://www.npmjs.com/package/react-dnd-html5-backend)
- [react-dnd-touch-backend](https://www.npmjs.com/package/react-dnd-touch-backend)
- [react-querybuilder](https://www.npmjs.com/package/react-querybuilder)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [jsonata](https://www.npmjs.com/package/jsonata)

## Usage

```tsx
import {
  QueryBuilderDocyrus
} from "@docyrus/ui/components/query-builder";
import type {
  QueryBuilderDocyrusProps,
  DocyrusQBField,
  RuleGroupType,
  RuleGroupTypeIC,
  RuleType,
  Field,
  FullField,
  FullOperator,
  FullCombinator,
  QueryBuilderProps,
  ActionProps,
  ValueSelectorProps,
  ValueEditorProps,
  NotToggleProps,
  DragHandleProps,
  CombinatorSelectorProps,
  FieldSelectorProps,
  OperatorSelectorProps,
  RuleGroupTypeAny,
  VersatileSelectorProps,
  QueryJsonataContext,
  EvaluateOptions,
  UseQuery2JsonataConverterOptions,
  UseQuery2JsonataConverterResult,
  ConvertQueryOptions,
  ConvertQueryResult,
  DateBindingSpec,
  OperatorApi,
  FilterGroup
} from "@docyrus/ui/components/query-builder";

<QueryBuilderDocyrus
  variant="default"
  size="sm"
  animated
  draggable
  showRuleNumbers
  maxDepth={0}
  emptyMessage={...}
  showClearButton
  clearButtonLabel={...}
  onRuleAdd={() => {}}
  onRuleRemove={() => {}}
  onGroupAdd={() => {}}
  onGroupRemove={() => {}}
  onClear={() => {}}
  enrichFieldDefaults
/>
```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Default style |
| `bordered` | Bordered — `rounded-lg border bg-card p-4 shadow-sm` |
| `compact` | Compact — `text-xs [&_.rule]:py-1 [&_.rule]:px-2 [&_.rule]:gap-1` |
| `striped` | Striped — `[&_.rule:nth-child(even)]:bg-muted/20` |

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Small — `[&_.qb-control]:h-7 [&_.qb-control]:text-xs` |
| `default` | Default |
| `lg` | Large — `[&_.qb-control]:h-10 [&_.qb-control]:text-sm` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `variant` | `"default"` \| `"bordered"` \| `"compact"` \| `"striped"` | `"default"` |
| `size` | `"sm"` \| `"default"` \| `"lg"` | `"default"` |
| `animated` | `boolean` | — |
| `draggable` | `boolean` | — |
| `showRuleNumbers` | `boolean` | — |
| `maxDepth` | `number` | — |
| `emptyMessage` | `ReactNode` | — |
| `showClearButton` | `boolean` | — |
| `clearButtonLabel` | `ReactNode` | — |
| `onRuleAdd` | `() => void` | — |
| `onRuleRemove` | `() => void` | — |
| `onGroupAdd` | `() => void` | — |
| `onGroupRemove` | `() => void` | — |
| `onClear` | `() => void` | — |
| `enrichFieldDefaults` | `boolean` | — |
| `className` | `string` | — |

## Components

| Component | Description |
|-----------|-------------|
| `QueryBuilderDocyrus` | Public export |

## Type Exports

| Type | Description |
|------|-------------|
| `QueryBuilderDocyrusProps` | — |
| `DocyrusQBField` | — |
| `RuleGroupType` | — |
| `RuleGroupTypeIC` | — |
| `RuleType` | — |
| `Field` | — |
| `FullField` | — |
| `FullOperator` | — |
| `FullCombinator` | — |
| `QueryBuilderProps` | — |
| `ActionProps` | — |
| `ValueSelectorProps` | — |
| `ValueEditorProps` | — |
| `NotToggleProps` | — |
| `DragHandleProps` | — |
| `CombinatorSelectorProps` | — |
| `FieldSelectorProps` | — |
| `OperatorSelectorProps` | — |
| `RuleGroupTypeAny` | — |
| `VersatileSelectorProps` | — |
| `QueryJsonataContext` | — |
| `EvaluateOptions` | — |
| `UseQuery2JsonataConverterOptions` | — |
| `UseQuery2JsonataConverterResult` | — |
| `ConvertQueryOptions` | — |
| `ConvertQueryResult` | — |
| `DateBindingSpec` | — |
| `OperatorApi` | — |
| `FilterGroup` | — |

## Type Reference

### DocyrusQBField

| Field | Type | Description |
|-------|------|-------------|
| `filterGroup` | `FilterGroup` | — |
| `fieldType` | `string` | — |
| `operatorValues` | `Record<string, QBOperatorValueOption[]>` | — |
| `operatorValueEditorType` | `Partial<Record<string, ValueEditorType>>` | — |

### QueryJsonataContext

| Field | Type | Description |
|-------|------|-------------|
| `activeUserId` | `string` | — |
| `activeUserTeamMemberIds` | `string[]` | — |

### EvaluateOptions

| Field | Type | Description |
|-------|------|-------------|
| `now` | `Date \| number` | — |
| `bindings` | `Record<string, unknown>` | — |

### UseQuery2JsonataConverterOptions

| Field | Type | Description |
|-------|------|-------------|

### UseQuery2JsonataConverterResult

| Field | Type | Description |
|-------|------|-------------|
| `expression` | `string` | — |
| `dateBindings` | `DateBindingSpec[]` | — |
| `unsupportedOperators` | `string[]` | — |
| `warnings` | `string[]` | — |
| `isValid` | `boolean` | — |
| `error` | `Error \| null` | — |
| `evaluate` | `(data: unknown, options?: EvaluateOptions) => Promise<boolean>` | — |

### ConvertQueryOptions

| Field | Type | Description |
|-------|------|-------------|
| `resolveGroup` | `(field: string) => FilterGroup \| undefined` | — |
| `fieldResolver` | `(field: string) => string` | — |
| `operatorOverrides` | `Record<string, (rule: RuleType, api: OperatorApi) => string \| null>` | — |
| `unsupportedFallback` | `boolean` | — |
| `weekStartsOn` | `0 \| 1` | — |

### ConvertQueryResult

| Field | Type | Description |
|-------|------|-------------|
| `expression` | `string` | — |
| `dateBindings` | `DateBindingSpec[]` | — |
| `unsupportedOperators` | `string[]` | — |
| `warnings` | `string[]` | — |

### DateBindingSpec

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `operator` | `string` | — |
| `amount` | `number` | — |

### OperatorApi

| Field | Type | Description |
|-------|------|-------------|
| `field` | `string` | — |
| `str` | `(value: unknown) => string` | — |
| `num` | `(value: unknown) => string` | — |
| `strArr` | `(values: unknown[]) => string` | — |
| `fieldRef` | `(name: string) => string` | — |

### FilterGroup

`"ALPHA"`