> For the complete documentation index, see [llms.txt](https://docs.fact-finder.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fact-finder.com/webcomponents-overview/api/navigation/filter-cloud.md).

# Filter Cloud

\`ff-filter-cloud\` lists filters applied to the current results. It lets users remove filters and supports custom templates, ordering, and facet inclusion rules.

## Documentation

Filter Cloud displays all filters that are currently selected. In its templates, it provides the related *Facet* and the selected *FacetElement*.

### Specifying templates

{% stepper %}
{% step %}

#### Add the Filter Cloud

You can use `ff-filter-cloud` by adding one line to your HTML code:

```html
<ff-filter-cloud></ff-filter-cloud>
```

A default template will be applied to all filters:

```html
<span data-template="filter">{{element.text}}</span>
```

{% endstep %}

{% step %}

#### Rendered HTML

When set up like in the example above, the rendered HTML could look like this:

```html
<ff-filter-cloud>
    <span data-template="filter">Element 1</span>
    <span data-template="filter">Element 2</span>
    <span data-template="filter">Element 3</span>
    <span data-template="filter">Element 4</span>
</ff-filter-cloud>
```

{% endstep %}

{% step %}

#### Customize filter element appearance

To customize filter element appearance, you can add an HTML element annotated with `data-template="filter"`. You can access the facet's display name through `{{facet.name}}`:

```html
<ff-filter-cloud>
    <span data-template="filter">{{facet.name}}: {{element.text}}</span>
</ff-filter-cloud>
```

{% endstep %}

{% step %}

#### Rendered HTML

When set up like in the example above, the rendered HTML could look like this:

```html
<ff-filter-cloud>
    <span data-template="filter">Group 1: Element 1</span>
    <span data-template="filter">Group 2: Element 2</span>
    <span data-template="filter">Group 3: Element 3</span>
    <span data-template="filter">Group 4: Element 4</span>
</ff-filter-cloud>
```

{% endstep %}

{% step %}

#### Add custom HTML

A custom filter template can be used with some additional custom HTML.

```html
<ff-filter-cloud>
    <h4>The Filter Cloud</h4>

    <div>
        <div>Custom above</div>

        <div data-template="filter" class="filter-element">
            <span>{{facet.name}}: {{element.text}}</span><span> ×</span>
        </div>

        <div>Custom below</div>
  </div>
</ff-filter-cloud>
```

{% endstep %}

{% step %}

#### Rendered HTML

When set up like in the example above, the rendered HTML could look like this:

```html
<ff-filter-cloud>
    <h4>The Filter Cloud</h4>

    <div>
        <div>Custom above</div>

        <div data-template="filter" class="filter-element">
            <span>Group 1: Element 1</span><span> ×</span>
        </div>
        <div data-template="filter" class="filter-element">
            <span>Group 2: Element</span><span> ×</span>
        </div>
        <div data-template="filter" class="filter-element">
            <span>Group 3: Element 3</span><span> ×</span>
        </div>

        <div>Custom below</div>
    </div>
</ff-filter-cloud>
```

{% hint style="info" %}
If no element annotated with `data-template="filter"` is specified, a console error will be displayed and the component will not render itself.

The only exception where `data-template="filter"` may be omitted is when `ff-filter-cloud` is left completely empty.
{% endhint %}
{% endstep %}

{% step %}

#### Invalid setup

The following is an error — `ff-filter-cloud` has no way of determining where to render its filter-item elements.

```html
<ff-filter-cloud>
    <span>Custom HTML</span>
</ff-filter-cloud>
```

{% endstep %}
{% endstepper %}

### Blacklist

If you want to exclude specific facets from the filter cloud, you can use the `blacklist` attribute. You may specify as many facets as you need, separated by commas. The values must correspond to the facets's `associatedFieldName` property returned by FactFinder.

#### Setup

This example will blacklist all filters applied by the `Price` and `Size` facets.

```html
<ff-filter-cloud blacklist="Price,Size">
    <div>
         <span data-template="filter">{{facet.name}}: {{element.text}}</span>
    </div>
</ff-filter-cloud>
```

### Whitelist

If you want to exclusively specify each facet, you can use the `whitelist` attribute. Like in blacklist, you may specify as many facets as you need, separated by commas. The values must correspond to the facet's `associatedFieldName` property returned by FactFinder.

#### Setup

This example will whitelist only filters applied by the `Brand` and `Category` facets.

```html
<ff-filter-cloud whitelist="Brand,Category">
    <div>
         <span data-template="filter">{{facet.name}}: {{element.text}}</span>
    </div>
</ff-filter-cloud>
```

### Filter click

There is only one delegated `click` listener for the filter elements, and it is attached to `ff-filter-cloud` itself. Click events on filter items bubble up to `ff-filter-cloud` and are processed there.

By default, clicking on a filter item removes it. You can attach your own `click` listener and call `event.stopPropagation()` to prevent default behavior.

See the example below that shows how to create a filter element with a clickable `x` button:

```html
<style>
    .btn-deselect {
        cursor: pointer;
    }
    .filter {
        cursor: default;
    }
</style>
<script>
    function userOnClick(event) {
        if (!event.target.classList.contains('btn-deselect')) {
            event.stopPropagation();
        }
    }
</script>
<ff-filter-cloud unresolved>
    <div data-template="filter" class="filter" onclick="userOnClick(event)">
        <span>{{element.text}}</span> <span class="btn-deselect">×</span>
    </div>
</ff-filter-cloud>
```

## Demo

{% embed url="<https://search-web-components.fact-finder.de/demos/5.x/ff-filter-cloud>" %}

## API

### `ff-filter-cloud`

#### Properties

| Name                                                                                                     | Description                                                                                                                                                                                                                                               |
| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **blacklist** (String) (default: undefined)                                                              | A comma-separated list of facet field names that should not appear in selected filters. Changing this value updates `ff-filter-cloud` without a FactFinder request. Do not use this with `whitelist`. The component throws an error and does not render.  |
| **order** (String) **Options**: "alphabetical", "fact-finder", "user-selection" (default: "fact-finder") | Sorts filter elements alphabetically, in FactFinder order, or by user selection. Changing this value updates the component without a FactFinder request. Unsupported values cause an error and prevent rendering.                                         |
| **whitelist** (String) (default: undefined)                                                              | A comma-separated list of facet field names that exclusively appear in selected filters. Changing this value updates `ff-filter-cloud` without a FactFinder request. Do not use this with `blacklist`. The component throws an error and does not render. |

#### Events

| Name            | Description                                                                                                                                  |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **dom-updated** | This event is triggered when the element has received new data and the template for this element and all sub elements have been punched out. |


---

# 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://docs.fact-finder.com/webcomponents-overview/api/navigation/filter-cloud.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.