Fluent Commerce Logo
Docs
Sign In

Complex Filter Configuration: Tips and Techniques

How-to Guide

Author:

Yulia Andreyanova

Changed on:

9 Apr 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.
No alt text provided

Steps

Step arrow right iconAdd the Component Skeleton to the Manifest

Begin by defining the structure for the `fc.field.filterComplex` component in the . 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}

Step arrow right iconConfigure 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}

Step arrow right iconCustomize 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 .

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}

Step arrow right iconConfigure 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 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).

Step arrow right iconSet 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}
No alt provided

Step arrow right iconDisplay 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}

Step arrow right iconConfigure 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 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}

Step arrow right iconHandle Selected Values

After items are selected and the modal window is closed, the chosen values must appear in the main input field. Use the `onChangeValues` property to achieve this.

The `onChangeValues` property determines how selected values are displayed in the input field and specifies their mapping to query variables. This configuration ensures a seamless transition between the filter’s modal window and the main input, keeping the interface user-friendly and functional.

1"extensions": {
2  "onChangeValues": {
3    "value": "node.ref",
4    "variableName": 'products_ref',
5    "visibleItemsThreshold",: 3
6  },
7}

Step arrow right iconFull 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}