ws-filter

The <ws-filter> WebComponent enables filtering of the search results or categories based on various product properties. It supports different filter types such as checkboxes, value ranges (range), sliders, image-based selection (image), and clickable labels (label). Both dynamically generated filters (e.g. colors) and individually defined custom filters (e.g. top sellers, availability) are supported.

Requirement

The component must be embedded inside <ws-filters>.
For the filter component to work correctly, the name="" attribute must contain the technical column name from the data feed. This name must be strictly lowercase. This column name specifies which product data field the filter refers to. Examples of possible column names are:
- price: For price filters.
- color: For color-selection filters.
- brand: For brand filters.
The column names in the data feed are defined through the data fields that are activated in the configuration of the search module and used for filtering, sorting, or search.

Dynamic and custom filters

The <ws-filter> component supports two types of filters: dynamic filters and custom filters. Both filter types can look the same in the frontend (e.g. as a checkbox).

Dynamic filters

Dynamic filters are based directly on the product data, that is, on information available in the data feed for each individual product. Typical examples are color, size, or brand. Typical use cases for dynamic filters:

Color (color)
Size (size)
Brand (brand)
Price (price)
Ingredients (ingredients)

Custom filters

Custom filters are not based on the individual values in the feed but on technically defined filter conditions (e.g. “stock ≥ 1”). Custom filters are therefore predefined filters where you decide exactly what should be filtered. Typical use cases:

Only available products (e.g. stock > 0)
“New arrivals” based on the creation date
Sale products (e.g. is_reduced = true)
Rating (e.g. rating >= 4)

Component for filters

The individual <ws-filter> elements for the filter items must always be placed inside <ws-filters>. If <ws-filters> is already present, additional filters can simply be added there.

Component for dynamic filters

The component can be embedded as follows on the category and search result page:

<ws-filters>
  ...

  <ws-filter type="checkbox" multiple="true" name="color"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="size"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="brand"></ws-filter>
  ...

  <ws-filter type="range" display-type="slider-fields" name="price"></ws-filter>
  ...

  <ws-filter type="checkbox" multiple="true" name="ingredients" negate></ws-filter>
  ...

  <ws-filter type="checkbox" multiple="true" name="ingredients" negate></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="neq_ingredients" negate></ws-filter>
  ...
</ws-filters>

Attributes
- type: Specifies the filter type.
  - checkbox: Selection via checkboxes (e.g. categories or colors).
    - negate: Enables the exclusion filter. Products that contain the selected filter values are not displayed. Only available with type="checkbox".
  - range: Slider for value ranges (e.g. price).
    - display-type: Presentation type of the range filter.
      - slider: Renders the range filter only as a slider.
      - fields: Renders the range filter only as number input fields (2 input fields).
      - slider-fields: Renders the range filter as a slider and number input fields.
  - image: Image-based selection via clickable images (e.g. colors, materials, patterns). See Image-based filters for details.
  - label: Clickable label options with hidden checkbox input (e.g. sizes). See Label filters for details.
- multiple="true": Allows multi-selection (for type="checkbox", type="image", and type="label", default for image and label: false).
- use-sort: Defines the order of the filter values. See Order of the filter values for details.
  - not specified: alphabetically ascending
  - count: by hit count, descending
  - numeric: numerically ascending. Replaces the previous attribute use-numeric-sort="true".
- data-template: Template for the labeling of the filter values with the placeholders {%value%} and {%count%}. Without this attribute, the filter only shows the value. Only takes effect with type="checkbox" and type="label". With type="image", the attribute is ignored. See Displaying the hit count per filter value for details.
- name: Defines the product data field the filter is applied to, e.g.
  - catids for categories
  - price for price

Product data fields used as filters are evaluated positively by default. If a field should filter alternatively or exclusively negatively, the negative variant must be activated in the configuration. The logic is controlled by the negate attribute inside <ws-filters>. If both variants should be available in parallel, use the technical field name with the prefix neq_ (e.g. neq_field_name) for the negative presentation. For exclusively negative use, no separate neq_ field is required. Important: For the neq_ field to exist at all, the negate attribute must additionally be set in the import module.If the user should be able to switch between include and exclude themselves, the ws-filter-toggle component is available for this.

Component for custom filters

The individual <ws-filter> elements for the filter items must always be placed inside <ws-filters>. The component can be embedded as follows on the category and search result page:

<ws-filters>
  ...
    <ws-filter type="checkbox" display-style="hide" name="salesrank" static-label="Top sellers only"></ws-filter>
    <ws-filter type="checkbox" display-style="hide" name="rating" static-label="Top-rated products only"></ws-filter>
    <ws-filter type="checkbox" display-style="hide" name="new_field" static-label="Newest products only"></ws-filter>
    <ws-filter type="checkbox" display-style="hide" name="inventory" static-label="Available products only"></ws-filter>
    <ws-filter type="checkbox" display-style="hide" name="reduced_field" static-label="Discounted products only"></ws-filter>
  ...
</ws-filters>

Attributes
- type: Specifies the filter type.
  - checkbox: Selection via checkboxes (e.g. categories or colors).
    - negate: Enables the exclusion filter. Products that contain the selected filter values are not displayed. Only available with type="checkbox".
- name: Defines the product data field the filter is applied to, e.g.
  - catids for categories
  - price for price
- disable-style: Specifies how the filter should behave when it contains no values:
  - hide: The filter disappears graphically.
  - inactive: The filter is simply inactive → does not react.
  - gray-out: The filter is grayed out and inactive.
  - line-through: The filter is struck through and inactive.
  - blur: The filter is blurred (2px) and inactive.
  - disable-style="disable-style": In addition to the predefined styles, you can also create a disable-style class and give it instructions in your own CSS file.
- static-label: Optional label text for displaying a custom text for a custom filter.

<ws-filter> instances must always be placed inside <ws-filters>. If <ws-filters> is already present, the custom filters can be added there.

Image-based filters (`type="image"`)

If you select the option type="image", the filter options are rendered as clickable images instead of text. You can use, for example, color swatches, material samples, or patterns. The filter works like a checkbox filter: a click on the image selects the value, another click deselects it.

<ws-filter
  type="image"
  name="color"
  image-path="/images/colorpick/"
  image-format="jpg"
  label-class="color-swatch"
  multiple="true">
</ws-filter>

Attributes
- image-path: Required. Path to the directory containing the images of the filter options. See “Image path” below for details.
- image-format: File format of the images. Possible values are jpg, png, and webp. Default: jpg
- image-map: JSON mapping from filter value to file name, for image names that deviate from the automatic name normalization.
- label-class: CSS class for the label element.
- multiple: Allows multi-selection. Default: false

Image name convention The component composes the image URL from three parts: image-path, the normalized filter value, and image-format. For the file name, the filter value is normalized:

Lowercase
Spaces become underscores
All characters except a to z, 0 to 9, _, and - are removed. Umlauts and ß are dropped without replacement.

Filter value	Image URL with `image-path="/images/colorpick/"` and `image-format="jpg"`
`Rot`	`/images/colorpick/rot.jpg`
`Dark Blue`	`/images/colorpick/dark_blue.jpg`
`Grün`	`/images/colorpick/grn.jpg`
`Weiß`	`/images/colorpick/wei.jpg`

If an image name deviates from this convention, the mapping can be defined via image-map. This is particularly important for values with umlauts or the letter ß. Map such values to the matching file names via image-map so that the component loads the correct image. Image path The value of image-path can be specified in two ways:

Path without domain such as /images/colors/ or images/colors/: The path is always resolved from the domain root of the shop. Both notations therefore result in the same URL, for example https://your-shop.com/images/colors/.
Full URL such as https://example.com/colors/: loads the images from the specified domain.

Behavior

The component inserts the image as an <img> element into the label of the filter option.
A tooltip shows the original value of the option.
Selected options receive the CSS class .checked on the label.
If an image cannot be loaded, the component automatically displays the text of the option. A missing image therefore does not result in an empty area.

Label filters (`type="label"`)

With type="label", filter options are rendered as clickable labels with a hidden checkbox input, e.g. for sizes that should be offered as buttons instead of a checkbox list.

<ws-filter
  type="label"
  name="size"
  label-class="size-class"
  data-template="{%value%} ({%count%})"
  multiple="true">
</ws-filter>

Attributes
- label-map: JSON mapping from filter value to display label (e.g. {"xl": "Extra Large"}), for display texts that deviate from the technical value.
- data-template: Template for the label content, for example {%value%} ({%count%}) for the value with hit count. See Displaying the hit count per filter value for details.
- label-class: CSS class for the label element.
- multiple: Allows multi-selection. Default: false

Behavior

The checkbox input is rendered hidden. Selection is done via the clickable label.
Selected options receive the CSS class .active on the label.

Displaying the hit count per filter value (data-template)

For each filter value, the search module returns the number of products in the current result that have this value. With the data-template attribute, this number is displayed next to the filter value. Without this attribute, the filter shows only the value, as before. Two placeholders are available in the template:

{%value%}: the filter value
{%count%}: the number of products with this value

<ws-filter type="checkbox" multiple="true" name="color" data-template="{%value%} ({%count%})"></ws-filter>

For the value “Rot” with 150 hits, the label reads Rot (150). You can freely define the text around the placeholders:

<ws-filter type="label" name="size" data-template="Größe '{%value%}' → {%count%} Ergebnisse"></ws-filter>

For size S with 20 hits, the label reads Größe 'S' → 20 Ergebnisse. How counting works

Products are counted, not variants. A product that has several variants with the value “Rot” is counted only once.
A value that the customer has excluded via an exclusion filter (negate) is no longer offered as an option in the positive filter of the same field. In the exclusion filter, it remains and usually keeps its real count, because the filter options of a field do not take into account the filters on the same field, including the exclusion. Only if the excluded value would otherwise be missing there does the search module add it with the count 0.

The search module only returns the hit count if values_with_counts is active in the filter configuration. This is the case by default. For the structure of the data in the response, see ws-search-result.

Order of the filter values (use-sort)

The search module returns the filter values sorted alphabetically. With the use-sort attribute, you define a different order:

Value	Order
not specified	Alphabetically ascending, for example “Blau, Grün, Rot”.
`count`	By hit count, descending. The value with the most products is at the top.
`numeric`	Numerically ascending, for example “2, 10, 20” instead of “10, 2, 20”. Replaces the previous attribute `use-numeric-sort="true"`.

<ws-filters>
  ...
  <ws-filter type="checkbox" multiple="true" name="brand" use-sort="count" data-template="{%value%} ({%count%})"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="groesse" use-sort="numeric"></ws-filter>
  ...
</ws-filters>

Sorting by hit count can be combined with data-template. This way, the customer sees why a value is placed higher up.

Sorting the filter values within a filter (custom order)

Domain-specific orders such as “Junior, Adult, Senior” or sizes such as “S, M, L, XL, XXL” can be represented neither alphabetically nor via use-sort. For this you can, for example, provide a sort list per filter that is stored via JavaScript in the template.

Static sort list (manually maintained)

The “Life stage” filter contains the values Adult, Junior, and Senior but should be sorted in the following order: Junior, Adult, Senior.

<ws-filters>
  ...
  <ws-filter type="checkbox" multiple="true" name="lebensphase"></ws-filter>
  ...
</ws-filters>

The sorting is implemented via the script:

<script type="text/plain" id="sort-list-lebensphase">
  ['Junior','Adult','Senior']
</script>

Attributes
- sort-list- = technical name of the product data field/filter, always lowercase (e.g. lebensphase).
- If new values are added, the list must be extended manually.

Sort list from the import (Wawi/ERP)

The “Life stage” filter contains the values Adult, Junior, and Senior but should be sorted in the following order: Junior, Adult, Senior.

<ws-filters>
  ...
  <ws-filter type="checkbox" multiple="true" name="lebensphase"></ws-filter>
  ...
</ws-filters>

The sorting is implemented via a script element in the template. The WS-FilterSortList() tag reads the sort list provided by the import.

Attributes
- WS-FilterSortList(FieldName) is case-sensitive → the field name must be used exactly as in the original (e.g. Lebensphase).
- In the script ID, sort-list- remains lowercase (sort-list-lebensphase).
- Providing this import list must be coordinated with Wawi/ERP.

Visibility of dynamic and custom filters (hiding)

Whether a filter is visible is controlled via the filter-container attribute, which must be assigned to HTML elements. For more information see ws-filters.

Filter values without effect on the result

If all products in the current result fulfill a specific filter value, the result is not narrowed down any further. Such values can be hidden. To do this, set the attribute hide-universal-options="true" on the surrounding <ws-filters>. By default, this option is deactivated and the values continue to be displayed. See ws-filters for details. Example:
In the category “Hundefutter” (dog food), all products have the value “Hund” (dog) for the filter “Tierart” (animal type). Selecting “Hund” would not change the result. With hide-universal-options="true", the value “Hund” is therefore not displayed in the filter “Tierart”. For exclusion filters (negate), this applies regardless of this option. A value that all products have in common cannot be excluded without the result becoming empty. It therefore does not appear as an option. Values that have already been selected positively are also not available in the exclusion filter.

HTML & CSS

CSS & styling for checkboxes

The component with the attribute type="checkbox" does not generate any specific CSS classes. No additional CSS instructions or HTML elements can be added inside the component. However, HTML elements and additional CSS styles can be added around the component to flexibly adjust the layout. For example, for type="checkbox" the component generates the following source code:

<input type="checkbox" value="blau" id="farbgrp-blau" name="farbgrp">
<label for="farbgrp-blau">blau</label>

<input type="checkbox" value="rot" id="farbgrp-rot" name="farbgrp">
<label for="farbgrp-rot">rot</label>

CSS & styling for image filters

With the image filter type, the image is inserted into the label as an <img> element. You therefore control the size and cropping of the image via the img in the label, not via background-size on the label. The label itself can be given its own CSS class via the label-class attribute, which can also be used to target the image (e.g. .color-swatch img). Selected options additionally carry the class .checked and can be marked accordingly (e.g. with a border or a check-mark overlay).

CSS & styling for label filters

With the label filter type, the checkbox input is hidden. Only the label is visible and can be styled with its own CSS class via the label-class attribute (e.g. as a button). Selected options additionally carry the class .active and can be highlighted accordingly.

CSS & styling for range sliders

noUiSlider is used for the range sliders, a JavaScript library that provides user-friendly sliders:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/noUiSlider/15.5.0/nouislider.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/noUiSlider/15.5.0/nouislider.min.js"></script>

For type="range", for example, the following source code is generated:

<ws-filter type="range" display-type="slider-fields" name="price">

  2.00

  4000.00

  <style class="slider-tooltip-style">
    .noUi-tooltip {
      display: none;
    }
  </style>
  <input type="number" name="price-min" class="range-field" min="2" max="3999" step="1"
      value="2"><input type="number" name="price-max" class="range-field" min="3" max="4000" step="1" value="4000">

</ws-filter>

Features of noUiSlider:

Dynamic range selection with two handles (e.g. price filter from 0 to 259 €)
Tooltips showing the current values
Customizable styling via CSS

The following classes are generated in the output and can be used for individual styling:

noUi-base: Base container of the slider.
noUi-connect: Area between the two slider handles (shows the selected range).
noUi-origin: Position of the respective slider handle.
noUi-tooltip: Tooltip that shows the current value of the handle.
noUi-handle: The actual handle that can be moved.

The noUiSlider library should be downloaded and can then be included directly or via the WEBSALE PageSpeed tool.

JavaScript workaround for displaying the currency symbol in a price range

The function must of course be executed when the filter is selected and, for example, also when items are loaded.

<script>
...
function wsPriceFilterCurrency() {
  var currencySymbol = document.createElement("span");
      currencySymbol.innerHTML = "~WS-CurrencySymbol~";
      currencySymbol = currencySymbol.innerText;
      var priceInputs = document.querySelectorAll("ws-filter[name='price'] input[type='number']");
      priceInputs.forEach(function(input) {
        var wrapper = input.closest(".range-field-wrapper");
        if (!wrapper) return;
        // Build new structure
        var inputGroup = document.createElement("div");
        inputGroup.className = "wsPriceFilterGroup";
        var prepend = document.createElement("div");
        prepend.className = "wsPriceFilterCurrency";
        prepend.textContent = currencySymbol;
        // Remove input from DOM and insert into new structure
        input.parentNode.removeChild(input);
        inputGroup.appendChild(prepend);
        inputGroup.appendChild(input);
        // Insert new structure in place of the original input
        wrapper.appendChild(inputGroup);
      });
    }
 ...
 </script>

URL filter parameters

Filters can be passed directly to the search module via the URL, e.g. for campaigns, preselections, or direct links with active filters. More about this in the documentation on URL filter parameters.

WS-Search

Setup

Integration into templates (Storefront)

Web components – Template placeholders

Web components – UI components

Requirement

Dynamic and custom filters

Dynamic filters

Custom filters

Component for filters

Component for dynamic filters

Component for custom filters

Image-based filters (`type="image"`)

Label filters (`type="label"`)

Displaying the hit count per filter value (data-template)

Order of the filter values (use-sort)

Sorting the filter values within a filter (custom order)

Static sort list (manually maintained)

Sort list from the import (Wawi/ERP)

Visibility of dynamic and custom filters (hiding)

Filter values without effect on the result

HTML & CSS

CSS & styling for checkboxes

CSS & styling for image filters

CSS & styling for label filters

CSS & styling for range sliders

JavaScript workaround for displaying the currency symbol in a price range

URL filter parameters

​Requirement

​Dynamic and custom filters

​Dynamic filters

​Custom filters

​Component for filters

​Component for dynamic filters

​Component for custom filters

​Image-based filters (type="image")

​Label filters (type="label")

​Displaying the hit count per filter value (data-template)

​Order of the filter values (use-sort)

​Sorting the filter values within a filter (custom order)

​Static sort list (manually maintained)

​Sort list from the import (Wawi/ERP)

​Visibility of dynamic and custom filters (hiding)

​Filter values without effect on the result

​HTML & CSS

​CSS & styling for checkboxes

​CSS & styling for image filters

​CSS & styling for label filters

​CSS & styling for range sliders

​JavaScript workaround for displaying the currency symbol in a price range

​URL filter parameters

Requirement

Dynamic and custom filters

Dynamic filters

Custom filters

Component for filters

Component for dynamic filters

Component for custom filters

Image-based filters (`type="image"`)

Label filters (`type="label"`)

Displaying the hit count per filter value (data-template)

Order of the filter values (use-sort)

Sorting the filter values within a filter (custom order)

Static sort list (manually maintained)

Sort list from the import (Wawi/ERP)

Visibility of dynamic and custom filters (hiding)

Filter values without effect on the result

HTML & CSS

CSS & styling for checkboxes

CSS & styling for image filters

CSS & styling for label filters

CSS & styling for range sliders

JavaScript workaround for displaying the currency symbol in a price range

URL filter parameters