---
alias: "fc.field.filterComplex"
aliases:
  - fc.field.filterComplex
category: field
module: Core
---
# fc.field.filterComplex

Complex multi-condition filter builder that dynamically fetches and filters data via a configurable GraphQL query. Opens a modal dialog with form fields, search results, and chip-based selection.

## When to Use
- Entity search fields requiring multi-step filtering (e.g., product lookup, location search)
- Forms where users must select entities from GraphQL query results
- Advanced filter inputs with custom search result card layouts

## Key Props
| Prop | Type | Required | What it controls |
|------|------|----------|------------------|
| `value` | `string[]` | No | Array of pre-selected values |
| `label` | string | No | Label for the main input field |
| `extensions` | Extensions | No | Advanced configuration (query, result layout, selection behavior) |

### Extensions Object
| Prop | Type | Required | What it controls |
|------|------|----------|------------------|
| `query` | string | **Yes** | GraphQL query for filtering data |
| `filtersSource` | string | No | Data source for filter options |
| `variables` | `Map<string, any>` | No | GraphQL query variables |
| `overrides` | ExtendedFormField | No | Field-level customization (label, default value, component) |
| `searchItemConfig` | MystiqueComponentInstance | **Yes** | Layout for search result items (Product Card or Standard Card) |
| `chipItemConfig` | `{ label: string, query: string, variables: Map }` | **Yes** | Chip display label path and pre-selection query |
| `onChangeValues` | OnChangeValues | **Yes** | Maps search item data to filter values |
| `exclude` | `string[]` | No | Filter fields to hide (e.g., `["createdOn"]`) |
| `mode` | `"single" \| "multiple"` | No | Selection mode. Default: `"multiple"` |
| `selectionLimit` | number | No | Max selectable items (only for `"multiple"` mode) |
| `displayColumns` | number | No | Number of form field columns. Default: `1` |
| `modalDimension` | `"small" \| "medium"` | No | Modal window size. Default: `"small"` |

### OnChangeValues Object
| Prop | Type | Required | What it controls |
|------|------|----------|------------------|
| `value` | string | No | Path to extract value from search item |
| `variableName` | string | No | GraphQL variable name for the value |
| `visibleItemsThreshold` | number | No | Min items shown before collapsing. Default: `2` |

### ExtendedFormField (overrides)
| Prop | Type | Required | What it controls |
|------|------|----------|------------------|
| `component` | string | No | Alternate field component alias |
| `source` | string | No | Setting name for dropdown/radio options |
| `label` | string | No | Custom label (supports i18n) |
| `value` | any | No | Lock field to a fixed value (hides field) |
| `defaultValue` | any | No | Initial editable value |
| `helperText` | string | No | Helper text alongside the field |
| `options` | `Record<string, string>` | No | Value options for select/radio |
| `sortPrefix` | string | No | Field position in form |

## Data Binding
The `query` in extensions defines the GraphQL query executed when the modal is opened and as filter fields change. `searchItemConfig` defines how results are displayed (typically via `fc.card.product` or `fc.card.attribute`). `chipItemConfig.query` runs an initial query to resolve labels for pre-selected values.

## Descendants
No.

## Gotchas
- Three required extension props: `query`, `searchItemConfig`, and `chipItemConfig` must all be configured.
- Selected items display as chips at the top of the modal; items remain visible in results after selection.
- When `mode: "single"`, output is a string; when `mode: "multiple"`, output is an array.
- `selectionLimit` is ignored when mode is `"single"`.
- Use `displayColumns: 2` or `3` for wider modals with many filter fields.

## Manifest Example
```json
{
  "component": "fc.field.filterComplex",
  "props": {
    "label": "Select Products",
    "extensions": {
      "query": "query products($ref: [String]) { variantProducts(ref: $ref) { edges { node { ref name } } } }",
      "searchItemConfig": {
        "component": "fc.card.product",
        "props": { "title": "{{node.name}}" }
      },
      "chipItemConfig": {
        "label": "node.name",
        "query": "query getProduct($ref: [String]) { variantProducts(ref: $ref) { edges { node { ref name } } } }",
        "variables": {}
      },
      "onChangeValues": {
        "value": "node.ref",
        "variableName": "ref"
      },
      "mode": "multiple",
      "selectionLimit": 10,
      "modalDimension": "medium",
      "displayColumns": 2
    }
  }
}
```

## AI Parse Notes
- **Primary intent:** Declarative Mystique component definition for manifests.
- **Selection signals:** Match by `alias`, category, and required `Key Props`.
- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
- **Safety checks:** Validate required props and data bindings before manifest generation.
