Complex Filter Configuration: Tips and Techniques
Author:
Yulia Andreyanova
Changed on:
28 Aug 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
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 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).
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 "searchItemConfig": {
36 "component": "fc.card.product",
37 "props": {
38 "title": "{{node.name}}",
39 "cardImage": {
40 "imageUrl": "{{node.attributes.byName.imageUrl}}"
41 },
42 "attributes": [
43 {
44 "value": "{{node.ref}}"
45 }
46 ]
47 }
48 },
49 "chipItemConfig": {
50 "label": "{{node.name}}",
51 "query": parse(gql`query products($products_ref: [String!], $products_name: [String!]) {
52 variant: variantProducts (ref: $products_ref, name: $products_name) {
53 edges {
54 node {
55 ref
56 name
57 }
58 }
59 }
60 standard: standardProducts (ref: $products_ref, name: $products_name) {
61 edges {
62 node {
63 ref
64 name
65 }
66 }
67 }
68 }`),
69 "variables": {
70 "products_first": 100,
71 },
72 },
73 "onChangeValues": {
74 "value": "node.ref",
75 "variableName": 'products_ref'
76 },
77 "exclude": [
78 "createdon",
79 "updatedon",
80 "type",
81 "status",
82 "gtin",
83 "summary",
84 "productcatalogue"
85 ],
86 "overrides": {
87 "name": {
88 "sortPrefix": 1
89 }
90 }
91 }
92}
