> For the complete documentation index, see [llms.txt](https://help.mimeeq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.mimeeq.com/configurator/options-and-widgets/filter-widget.md).

# Filter Widget

Help customers find the right material fast in large collections. Learn how to create filters, tag your options and set up the Filter Widget.

The Filter Widget lets customers narrow down configurator options when browsing large collections of materials, fabrics or other customisation choices. It is especially useful for extensive option sets that would otherwise need long scrolling.

![Filter Widget in the configurator option panel with filter icon and search](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FELFNASe5YCh2t04IXs6w%2Ffilter-11_5ec13.png?alt=media)

***

## How to create and use filters

Before creating a Filter Widget, you need to set up two things:

1. Create filter categories (like "Colour" or "Material").
2. Connect these filters to your configurator options.

{% hint style="warning" %}
If you skip this step, the filter button won't show up on your configurator page, and customers won't be able to filter anything.
{% endhint %}

{% hint style="info" %}
Think of it this way: you're creating tags for your materials, and the Filter Widget uses these tags to help customers find what they want.
{% endhint %}

{% stepper %}
{% step %}

### Create filters

1. Go to **Settings → Widgets → Filter Widget → Filter Lists**.
2. Click **Add Filter** to create a filter.

   ![Filter Lists page with the Add Filter button](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2F4Nd1H3D5svJHBKsVnanz%2Ffilter-21_1txprco.png?alt=media)
3. Add a name (for example, "Fabric Colour").
4. Select a position (**Parent** or **Assigned to Parent**). This helps you group your filters under categories.
5. If it's a **Parent** filter, click **Save Changes**.
6. If it's **Assigned to Parent**, select a parent filter, then select a preview type: **No Preview**, **Colour** or **Thumbnail**.
7. Click **Save Changes**.

   ![Filter assigned to a parent with a colour preview](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FieplDnHbNcY9PB3xeJ7v%2Ffilter-31-new_6d4un5.png?alt=media)

{% hint style="info" %}
Preview type helps users identify filters visually. With **Colour**, you choose a colour from the colour picker to display a swatch next to the filter name. With **Thumbnail**, you upload a custom image or icon (such as a material texture or category indicator) that appears next to the filter name.
{% endhint %}

{% hint style="info" %}
Filters can be used both in Filter Widgets and in Rules as Triggers and Actions, allowing for powerful and dynamic logic. Turn on **Hide from Filter Widget** only if you want to use this filter exclusively for Rules.
{% endhint %}

**Filter category ideas:**

* Colour
* Price Groups
* Manufacturer
* Range
* Purpose
* ECO Friendly
  {% endstep %}

{% step %}

### Assign filters to options

1. Go to your **Option Set** and select the Option Set you want to assign filters to.
2. Open each option (or bulk select) in the set for editing.
3. Find the **Filters** column.
4. On hover, you will see an **Add** button. Click it to open a drawer with a list of all available filters.
5. Check all boxes that apply to that specific material. For example, a Blue Leather material might have Colour: Blue and Material Type: Leather.
6. Save your changes. Repeat for all materials in your option sets.

   ![Filters column in an option set with the drawer of available filters open](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2Fu8xhKrWap39OdXf3GNDJ%2Ffilter-411-new_1umwbws.png?alt=media)

{% hint style="success" %}
Time-saving tip: select multiple options in bulk and assign the same filters to all of them at once. This is especially helpful when groups of materials share the same properties.
{% endhint %}
{% endstep %}

{% step %}

### Create the Filter Widget

Now that you've created your filters and assigned them to your option sets, you're ready to create a Filter Widget.

1. Navigate to the configurator you want to edit, open the **Options** tab and click **New**.
2. Select **Linked** or **Manual** as the **Mode** type.
3. Select the **Filter Widget** type.
4. Configure the widget according to your preferences (see the table below).
   {% endstep %}
   {% endstepper %}

***

## Filter Widget settings

<table><thead><tr><th width="57.359375">#</th><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>1</td><td><strong>Name</strong></td><td>The Option Block Name that will be visible to customers.</td></tr><tr><td>2</td><td><strong>Mode</strong></td><td>Select either <strong>Linked</strong> or <strong>Manual</strong>. <strong>Linked</strong> means it will be connected to an existing Option Set or Collection. <strong>Manual</strong> means you will create an Option Set specifically for this configurator only.</td></tr><tr><td>3</td><td><strong>Option Set Source</strong></td><td>Select either <strong>Collection</strong> or <strong>Option Set</strong> to define where the thumbnail options will come from.</td></tr><tr><td>4</td><td><strong>Widget Type</strong></td><td>Select <strong>Thumbnail</strong> to create a visual, grid-based display of options.</td></tr><tr><td>5</td><td><strong>Widget Source</strong></td><td>Define if settings come from Global Template or Local Settings.</td></tr><tr><td>6</td><td><strong>Number of columns</strong></td><td>Define how many thumbnails will appear in each row on desktop.</td></tr><tr><td>7</td><td><strong>Number of columns on mobile</strong></td><td>Define how many thumbnails will appear in each row on mobile devices.</td></tr><tr><td>8</td><td><strong>Show Caption</strong></td><td>If enabled, shows the name of each individual option as a text caption beneath its thumbnail.</td></tr><tr><td>9</td><td><strong>Filter Widget Type</strong></td><td><strong>Expanded</strong> (shows all options directly) or <strong>Compact</strong> (creates a collapsible menu).</td></tr><tr><td>10</td><td><strong>Show Keyline</strong></td><td>Adds a border around each thumbnail. This is useful when thumbnails might blend with the background.</td></tr><tr><td>11</td><td><strong>Image Style</strong></td><td>Choose between <strong>Square</strong> or <strong>Round</strong> thumbnails depending on your preferred design.</td></tr><tr><td>12</td><td><strong>Show Thumbnails Search</strong></td><td>Adds a search input field near the filter icon. By default, allows searching options by name, code, option set name or filter name.</td></tr><tr><td>13</td><td><strong>Show Search Field in Modal</strong></td><td>Adds a search input to the Filter Modal allowing users to search by filter name.</td></tr><tr><td>14</td><td><strong>Show Personal Filter Bar</strong></td><td>Displays selected filters as chips under the filter icon. This feature is available only for desktop view.</td></tr><tr><td>15</td><td><strong>Filter Display Mode</strong></td><td>Defines how filters will be presented in the Modal: either <strong>Always Visible</strong> or <strong>Expandable</strong>.</td></tr><tr><td>16</td><td><strong>Default state</strong></td><td>Available only when <strong>Expandable</strong> Filter Display Mode is selected. Defines the default state for filter lists: <strong>First Open</strong>, <strong>All Open</strong> or <strong>All Closed</strong>.</td></tr><tr><td>17</td><td><strong>Add Option Set</strong></td><td>After configuring the widget settings, click the <strong>Add</strong> button to add an Option Set to this widget.</td></tr></tbody></table>

![Filter Widget settings in the configurator Options tab](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FUNqm18dSjkr0QO1An2iE%2Ffilter-51_1iw7p3f.png?alt=media)

***

## How the Filter Widget appears with different configurations

### Filter Widget types

There are two Filter Widget types:

| # | Type         | How it displays                                                                                | Best for                                 |
| - | ------------ | ---------------------------------------------------------------------------------------------- | ---------------------------------------- |
| 1 | **Expanded** | Shows all options directly inside the option panel                                             | Fewer options                            |
| 2 | **Compact**  | Creates a collapsible menu that, when clicked, opens another drawer with all available options | Many option sets and options within them |

{% hint style="warning" %}
If the filter indicator doesn't appear on your configurator page, it almost always means you haven't defined filters or assigned them to your materials. This is the most common issue when setting up Filter Widgets.
{% endhint %}

Both widget types can be configured with or without a search function. In the first image, example 1 shows the expanded widget with search and example 2 shows the expanded widget without search.

![Expanded Filter Widget with search (1) and without search (2)](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FRwpHC5IackkMqaXH4hEs%2Ffilter-81_7bnwmf.png?alt=media)

In the images below, example 1 shows the compact widget as it appears inside the option panel. Example 2 shows the compact widget once clicked, with search and the personal filter bar.

![Compact Filter Widget in the option panel (1) and opened with search and personal filter bar (2)](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2Fpvr1mvmgIhW7X7coerhk%2Ffilter-101_17jxtn2.png?alt=media)

{% hint style="warning" %}
You cannot have two expanded widgets in one group. If you attempt this, they will be presented as compact by default.
{% endhint %}

### Personal filter bar display

On desktop, you can show or hide the personal filter bar. When it's on, selected filters appear as chips under the filter icon and a search input inside the filter widget, either Compact or Expanded.

* **Clear one filter:** click the X on a chip without opening the filter modal.
* **Clear all filters:** click the **Reset Filters** button at the end to reset all filters without opening the filter modal.

In example 1, we show the option without a personal filter bar. In example 2, we show the option with the filter bar on.

![Option panel without (1) and with (2) the personal filter bar](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FyklGP41UZwV0Un5Hfxlo%2Ffilter-71_akmupe.png?alt=media)

### Filter modal options

Inside the filter modal, you can show a search bar to search by filter name. Filters can be either always visible or expandable. Expandable filters can be collapsed and hidden, which makes navigation easier when there are many options.

The shape of the filter pill and preview follows the filter's **Image Style** setting:

* **Square:** the filter pill appears as a square shape with slightly rounded corners, and the preview keeps a square format.
* **Round:** the filter pill becomes fully rounded.

This consistent styling keeps your interface visually coherent.

In the image, example 1 shows a modal without search, with always visible filters in square style. Example 2 shows a modal with search and collapsible filters in round style. By default, the first one is open.

![Filter modal with always visible square filters (1) and searchable collapsible round filters (2)](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FjRPJCuCE8pM6hFtvdWzv%2Ffilter-61-new_mhr35v.png?alt=media)

***

## Best practices

* Create filter categories and assign them to all materials before setting up the widget.
* Use **Expanded** for fewer options and **Compact** when you have multiple option sets.
* Place the most commonly used filters at the top of your categories list.
* Keep filter names intuitive and concise so customers understand what they're filtering by.
* Add search when you have large option collections to help customers find specific items quickly.
* Consider using the **Personal Filter Bar** for desktop users to make their selected filters more visible.
* Always preview your configurator after setup to verify the filter button appears and works correctly.

***

## Related articles

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Local &#x26; Global Templates</strong></td><td>Share widget settings across configurators or customise them per product.</td><td><a href="/configurator/options-and-widgets/local-and-global-templates.md">Local &amp; Global Templates</a></td></tr><tr><td><strong>Thumbnail Widget</strong></td><td>Display option sets as a visual grid of swatches or images.</td><td><a href="/configurator/options-and-widgets/thumbnail-widget.md">Thumbnail Widget</a></td></tr><tr><td><strong>Hiding Options</strong></td><td>Control which options appear in the option panel and specifications.</td><td><a href="/configurator/options-and-widgets/hiding-options.md">Hiding Options</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.mimeeq.com/configurator/options-and-widgets/filter-widget.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.