> 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

Learn how to set up and use Filter Widget to help customers easily narrow down configurator options when browsing large collections.

Filter Widget provide an intuitive way to narrow down configurator options when browsing through large collections of materials, fabrics, or other customization choices. They're especially useful when you have extensive option sets that would otherwise require users to scroll through long lists.

This guide will walk you through how to set up and effectively use Filter Widget.

![Filter Widget Example](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 "Color" or "Material")
2. Connect these filters to your configurator options

If you skip this step, the filter button simply won't show up on your configurator page, and customers won't be able to filter anything.

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

### To create filters:

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

![How to create Filters](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 (e.g., "Fabric Colour")
4. Select 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, continue with these steps:

* Select a parent filter
* Select a preview type - No Preview, Colour, Thumbnail

{% hint style="info" %}
Preview type helps users quickly identify filters visually. When you select "Colour," you can choose a color from the color picker to display a color swatch next to the filter name. When you select "Thumbnail," you can upload a custom image or icon (such as material textures, or category indicators) that will appear next to the filter name.
{% endhint %}

7. Click "Save Changes"

![Example of Filter with a 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" %}
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

### Assigning Filters to Options

1. Go to your Option Set → Select the Option Set you want to assign filters to
2. Open each option (or bulk select) in the set for editing
3. Find column "Filters"
4. On hover, you will see an "Add" button. Click this button 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:

* Color: Blue
* Material Type: Leather

6. Save Your Changes. Repeat for all materials in your option sets

{% hint style="info" %}
Time-saving tip: To speed up the process, you can select multiple options in bulk and assign the same filters to all of them at once. This is especially helpful when you have groups of materials that share the same properties.
{% endhint %}

![How to Assign Filters to Options](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)

## How to Create 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 Options tab and click "New"
2. Select Linked or Manual as the Mode type
3. Select Filter Widget Type
4. Configure the widget according to your preferences

Below is a table detailing various options for the Filter Widget and their descriptions:

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

![Filter Widget Setup](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 Filter Widget Appears with Different Configurations

### Filter Widget Types

There are two main types of filter widgets: Expanded and Compact. The expanded widget shows all options directly inside the option panel. The compact widget creates a collapsible menu that, when clicked, opens another drawer with all available options. Compact widgets make sense when you have many option sets and options within those option sets.

{% hint style="warning" %}
If the filter indicator doesn't appear on your configurator page, it almost always means you haven't properly 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 Type](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 bellow, example 1 shows the compact widget as it appears inside the option panel, and example 2 demonstrates how the compact widget looks once clicked, with search and personal filter bar.

![Compact Filter Widget Type](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, we have an option to show or hide the personal filter bar. When it's on, the selected filters will appear as chips under the filter icon and a search input inside the filter widget, either Compact or Expanded. Each chip represents a selected filter, and you can clear individual filters by clicking the X on the chip without accessing the filter model. You also have a "Reset Filters" button at the end that allows you to reset all filters without going inside the filter model.

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

![Personal Filter Bar Display](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 have an option to show a search bar, which you can search by filter name. You also can have either always visible or expandable filters, which means that if you select expandable filters, they can be collapsed and hidden to make it easy to navigate if there are a lot of options.

The shape of the filter pill and preview is connected to the filter's image style setting. When image style is set to "Square," the filter pill appears as a square shape with slightly rounded corners, and the preview maintains a square format. When image style is set to "Round," the filter pill becomes fully rounded. This consistent styling helps maintain visual harmony across your interface.

In the image, example 1 shows example without search and always visible filters with square style. In the example number 2, we show the example with search and with collapsible filters with rounded style. By default, the first one is open.

![Filter Modal Options](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

* Properly 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 can easily understand what they're filtering by.
* Add search functionality 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.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.