Complex Filter Configuration: Tips and Techniques

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

How-to Guide

Author:

Yulia Andreyanova

Changed on:

12 Dec 2025

Key Points

This guide offers step-by-step instructions for setting up and customizing the Complex Filter component to achieve precise and efficient data filtering.
Learn how to set up data sources, use GraphQL queries, and display results easily with card components like Standard Card and Product Card.
Discover how to customize fields by changing their types, adjusting the field order, and removing unnecessary ones to make the filter simple and effective for your needs.

Prerequisites

Settings Creation and Editing Mutations

Steps

Add the Component Skeleton to the Manifest

Begin by defining the structure for the `fc.field.filterComplex` component in the manifest. Include properties for filters, queries, and configurations:

1{
2    "component": "fc.field.filterComplex",
3    "label": "Product filter",
4    "extensions": {
5        "filtersSource": "",
6        "query": "",
7        "variables": {},
8        "overrides": {},
9        "searchItemConfig": {},
10        "chipItemConfig": {},
11        "onChangeValues": {},
12        "mode": "single",
13        "exclude": []
14    }
15}

Configure Data Source

Define the `query` and `variables` to retrieve the desired data. This enables the component to fetch entities dynamically.

1"extensions": {
2  "query": parse(gql`query products($products_ref: [String!], $products_name: [String!], $productCatalogue: String!) {
3    variant: variantProducts (ref: $products_ref, name: $products_name, catalogue: {ref: $productCatalogue}) {
4      edges { 
5        node { ref name attributes { name value } }
6      }
7    }
8    standard: standardProducts (ref: $products_ref, name: $products_name, catalogue: {ref: $productCatalogue}) {
9      edges {
10        node { ref name attributes { name value } }
11      }
12    }
13  }`),
14  "variables": {
15    "products_first": 100,
16    "productCatalogue": "{{productCatalogue}}"
17  },
18}

Customize Fields

To refine the displayed data, unwanted fields can be excluded by adding their names to the `exclude` property. The `overrides` property can be used to customize field types, labels, and order.

1"extensions": {
2  "overrides": {
3    "name": {
4      "sortPrefix": 1
5    },
6  },
7  "exclude": [
8    "createdon",
9    "updatedon",
10    "type",
11    "status",
12    "gtin",
13    "summary",
14    "productcatalogue"
15  ]
16}

Configure Wildcard Search Behavior for Complex Filter Fields

To control how text-based values (such as name, ref, city, etc.) are matched inside a Complex Filter modal, you can configure wildcard search behavior directly at the field level using the two-layer wildcard model.By applying the `wildcardFilter` property inside a field’s override, you can fine-tune how filter input is translated into search patterns:

`prefix: true` → allow leading wildcard (`%value`)
`postfix: true` → allow trailing wildcard (`value%`)
`prefix: false` & `postfix: false` → exact match
`undefined` → treated as false (no wildcard)

1{
2  "extensions": {
3    "overrides": {
4      "name": {
5        "extensions": {
6          "wildcardFilter": {
7            "prefix": false,
8            "postfix": true
9          }
10        }
11      }
12    }
13  }
14}

How It Works

The `wildcardFilter` property is evaluated before the account-level wildcard configuration.
Wildcard behavior applies only to the search input inside the Complex Filter modal.

When to Use This

Use field-level wildcard configuration in Complex Filter when:

You need exact search for identifiers, SKU-like codes, or phone numbers
You want partial matching only for specific fields (e.g., names, cities)
You require different search behavior in different Complex Filter Fields
You want to improve performance by removing unnecessary wildcards
You need consistent backend-safe queries for fields that cannot accept wildcards

Configure Selection Behavior

Control how users interact with the filter using the `mode` and `selectionLimit` properties.

1{
2    "extensions": {
3        "mode": "multiple",
4        "selectionLimit": 5
5    }
6}

The `mode` property controls how many items a user can select. When set to `single`, only one item can be chosen, and the selected value is returned as a string. When set to `multiple` (the default), users can select multiple items, and the output is returned as an array. The `selectionLimit` property, which only applies when `mode` is `multiple`, restricts the number of selectable items to a specified maximum (e.g., 5 means users can choose up to five items).

Consistent Configuration Required

Avoid setting different values for `mode` and `selectionLimit` for the same entity across related pages. This can cause missing data and unpredictable system behavior.

Set Modal Size and Layout Columns

Use `modalDimension` and `displayColumns` to configure the filter modal layout.

`modalDimension`: This controls the modal size. It accepts `small` (the default) or `medium`. This is useful when you expect longer labels or want more visual breathing room.
`displayColumns`: This setting defines the number of columns for the field layout. Set it to `2` or `3` to group more fields horizontally, making better use of screen space.

1"extensions": {
2  "modalDimension": "medium",
3  "displayColumns": 2
4}

Display Search Results

Choose between the fc.card.product or fc.card.attribute components to visualize search results. Configure how results are presented using the `searchItemConfig` property.

1"extensions": {
2  "searchItemConfig": {
3    "component": "fc.card.product",
4    "props": {
5      "title": "{{node.name}}",
6      "cardImage": {
7        "imageUrl": "{{node.attributes.byName.imageUrl}}"
8      },
9      "attributes": [
10        {
11          "value": "{{node.ref}}"
12        }
13      ]
14    }
15  },
16}

Configure Selected Items Display

Use the `chipItemConfig` property to define how selected items are displayed in the filter’s modal window. This configuration can include additional query and variable properties to specify a GraphQL query for preselected items. For instance, the filter panel might supply a list of references already selected without opening the complex filter. If these properties are not defined, the main query will be used by default.

1"extensions": {
2  "chipItemConfig": {
3    "label": "{{node.name}}",
4    "query": parse(gql`query products($products_ref: [String!], $products_name: [String!]) {
5      variant: variantProducts (ref: $products_ref, name: $products_name) {
6        edges { node { ref  name }}
7      }
8      standard: standardProducts (ref: $products_ref, name: $products_name) {
9        edges {  node { ref name } }
10      }
11    }`),
12    "variables": {
13      "products_first": 100,
14    },
15  },
16}

Handle Selected Values

When items are selected and the modal window is closed, the chosen values are displayed in the main input field according to the `chipItemConfig` property. This behavior is managed through `onChangeValues`.The `onChangeValues` property defines how selected values are mapped to query variables, ensuring that the correct data is sent to the backend when filters are applied.The `outputTemplate` property specifies how a field’s value is transformed before being passed to the backend. It is required when the backend expects a format other than a simple string or array of strings, such as an object or an array of objects. This mechanism ensures compatibility with backend requirements and removes the need for additional client-side transformation logic.

1{
2  "extensions": {
3    "onChangeValues": {
4      "value": "node",
5      "outputTemplate": "{\"ref\": \"{{node.ref}}\"}"
6    }
7  }

Full Configuration Example

Below is a comprehensive example of the fully configured `fc.field.filterComplex` component:

1"productRef": {
2  "component": "fc.field.filterComplex",
3  "label": "Product filter",
4  "extensions": {
5    "query": parse(gql`query products($products_ref: [String!], $products_name: [String!], $productCatalogue: String!) {
6      variant: variantProducts (ref: $products_ref, name: $products_name, catalogue: {ref: $productCatalogue}) {
7        edges { 
8          node {
9            ref
10            name
11            attributes {
12              name
13              value
14            }
15          }
16        }
17      }
18      standard: standardProducts (ref: $products_ref, name: $products_name, catalogue: {ref: $productCatalogue}) {
19        edges {
20          node {
21            ref
22            name
23            attributes {
24              name
25              value
26            }
27          }
28        }
29      }
30    }`),
31    "variables": {
32      "products_first": 100,
33      "productCatalogue": "{{productCatalogue}}"
34    },
35
36    "modalDimension": "medium",
37    "displayColumns": 2,
38
39    "searchItemConfig": {
40      "component": "fc.card.product",
41      "props": {
42        "title": "{{node.name}}",
43        "cardImage": {
44          "imageUrl": "{{node.attributes.byName.imageUrl}}"
45        },
46        "attributes": [
47          {
48            "value": "{{node.ref}}"
49          }
50        ]
51      }
52    },
53
54    "chipItemConfig": {
55      "label": "{{node.name}}",
56      "query": parse(gql`query products($products_ref: [String!], $products_name: [String!]) {
57        variant: variantProducts (ref: $products_ref, name: $products_name) {
58          edges {
59            node {
60              ref
61              name
62            }
63          }
64        }
65        standard: standardProducts (ref: $products_ref, name: $products_name) {
66          edges {
67            node {
68              ref
69              name
70            }
71          }
72        }
73      }`),
74      "variables": {
75        "products_first": 100
76      }
77    },
78
79    "onChangeValues": {
80      "value": "node.ref",
81      "variableName": "products_ref"
82    },
83
84    "exclude": [
85      "createdon",
86      "updatedon",
87      "type",
88      "status",
89      "gtin",
90      "summary",
91      "productcatalogue"
92    ],
93
94    "overrides": {
95      "name": {
96        "sortPrefix": 1,
97        "extensions": {
98          "wildcardFilter": {
99            "prefix": false,
100            "postfix": true
101          }
102        }
103      }
104    }
105  }
106}

Complex Filter Configuration: Tips and Techniques

Key Points

Prerequisites

Settings Creation and Editing Mutations

Steps

Add the Component Skeleton to the Manifest

Configure Data Source

Customize Fields

Configure Wildcard Search Behavior for Complex Filter Fields

Configure Selection Behavior

Set Modal Size and Layout Columns

Display Search Results

Configure Selected Items Display

Handle Selected Values

Full Configuration Example

Related artifacts

Complex Filter Component

Product Card Component

Attribute Card Component

Related content

Complex Filter Component

Yulia Andreyanova

Knowledge Tracks Related To This Topic

Building Blocks

By Type

Helpful Resources

Quick Links