> 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/web-components-4.x./api/basic-elements/suggest.md).

# Suggest

Build and customize interactive FactFinder suggestions.

## Documentation

## API reference

**`ff-suggest`**

<details>

<summary>Properties</summary>

| Property                                    | Description                                                                      |
| ------------------------------------------- | -------------------------------------------------------------------------------- |
| **layout** (String, default `"list"`)       | Displays sections as a list or block.                                            |
| **suggest-items** (Array)                   | Data from FactFinder.                                                            |
| **hide-onblur** (String, default `"false"`) | Closes after clicks outside Suggest and its search box. `"true"` is recommended. |

</details>

<details>

<summary>Events</summary>

| Event                                      | Description                                              |
| ------------------------------------------ | -------------------------------------------------------- |
| **suggest-item-clicked** / **dom-updated** | Fires on item click, or after data and templates render. |

</details>

**`ff-suggest-item`**

<details>

<summary>Properties</summary>

| Property                           | Description                                         |
| ---------------------------------- | --------------------------------------------------- |
| **type** (String, default `"all"`) | `product`, `brand`, `search`, `category`, or `all`. |
| **suggestion**                     | Data for one item.                                  |

</details>

<details>

<summary>Events</summary>

| Event                                | Description                                     |
| ------------------------------------ | ----------------------------------------------- |
| **item-clicked** / **before-search** | Fires on click or before this element searches. |

</details>

### The basics

**Two features in one element**

The `ff-suggest` element can render both regular **Suggestions** and **Popular Searches**.

This article focuses on the setup for regular suggestions.

See the Popular Searches article for details.

**Templating concept**

The suggestions template is defined through a `template` element with the `data-role="suggestions"` attribute.

It only accepts `section` elements at the root level. This is due to legacy constraints. A future version will remove this requirement.

```html
<ff-suggest no-auto-highlight>
    <template data-role="suggestions">
        <section>
            <!--content-->
        </section>
        <section>
            <!--content-->
        </section>
    </template>
</ff-suggest>
```

{% hint style="info" %}
All code listings use the `no-auto-highlight` attribute on `ff-suggest`.

We strongly recommend to always set it. See the section on *Hit highlighting* for details.
{% endhint %}

### Adding a Suggest container

You need to annotate an element with the `data-container="suggestType"` attribute for each suggest type configured in the FactFinder UI.

The `ff-suggest` element hides the annotated container if no suggestions are found for this type.

In addition, you need to add an `ff-suggest-item` element inside the container. All received suggestions of this `"suggestType"` are inserted at this position and will be an exact copy of this element.

`ff-suggest-item` supports image binding.

Repeat this process for all configured `"suggestTypes"`.

```html
<ff-suggest no-auto-highlight>
    <template data-role="suggestions">
        <section>
            <div data-container="suggestType">
                <span>Suggestions for suggestType</span>
                <div>
                    <!--ff-suggest-items are always added at the original position of the template-->
                    <ff-suggest-item type="suggestType">
                        <div>{{{ff-hitHighlight name}}}</div>
                        <img width="100" height="100" data-image />
                    </ff-suggest-item>
                </div>
            </div>
        </section>
    </template>
</ff-suggest>
```

**Hit highlighting**

You can highlight the parts in the Suggest's response that match the query in the search box.

Matches are wrapped in a `<span class="ffw-query">` element so you can apply appropriate CSS.

Using hit highlighting requires three parts:

* Set the `no-auto-highlight` attribute on `ff-suggest`.
* Use triple curly braces in the data binding.
* Add the `ff-hitHighlight` formatter into the data binding.

The triple curly braces in `<span>{{{ff-hitHighlight name}}}</span>` tell the template engine to interpret the HTML instead of render it as plain text.

See Template for details.

The `ff-hitHighlight` formatter wraps the text in the relevant HTML without modifying the original data.

{% hint style="info" %}
The `no-auto-highlight` attribute is necessary to prevent the component from overwriting the suggest-item's original data with the HTML wrapper instead of applying it only to the display layer.

This is an internal artifact of an old integration method. In a future version, `no-auto-highlight` will become redundant.
{% endhint %}

**Rendered HTML**

Container templates provided inside the `ff-suggest` tag will be rendered inside several additional `div` elements.

For example, consider the following HTML **setup**.

```html
<ff-suggest no-auto-highlight>
    <template data-role="suggestions">
        <section>
            <div data-container="suggestType">
                <span>Suggestions for suggestType</span>
                <div>
                    <ff-suggest-item type="suggestType">
                        <span>{{{name}}}</span>
                    </ff-suggest-item>
                </div>
            </div>
        </section>
    </template>
</ff-suggest>
```

Suppose there are two suggestions of `suggestType`. This will result in the following HTML **output**.

```html
<ff-suggest layout="list" no-auto-highlight>
    <div style="position:relative;width:100%">
        <div class="ffw-suggestContainerWrapper">
            <div class="ffw-suggestContainer ffw-listLayout">
                <section>
                    <div data-container="suggestType">
                        <span>Suggestions for suggestType</span>
                        <div>
                            <ff-suggest-item type="suggestType">
                                <span><span class="ffw-query">Sugg</span>estion 1</span>
                            </ff-suggest-item>
                            <ff-suggest-item type="suggestType">
                                <span><span class="ffw-query">Sugg</span>estion 2</span>
                            </ff-suggest-item>
                        </div>
                    </div>
                </section>
            </div>
        </div>
    </div>
</ff-suggest>
```

**When the template clashes with 3rd party frameworks**

3rd party rendering frameworks might also use the `template` element to define their templates.

It can happen that those frameworks 'steal' the template from Web Components and leave a broken `ff-suggest`.

There are two fallback methods to define the templates for `suggestions` and `popularSearches`. While the wrapping `template` tag is replaced, the template's body remains the same.

Your rendering framework might accept one these approaches.

{% tabs %}
{% tab title="Via `script` tag" %}

```html
<ff-suggest no-auto-highlight>
    <script type="text/ff-compat-template" data-role="suggestions">
        <section>...</section>
    </script>
</ff-suggest>
```

{% endtab %}

{% tab title="Via comment" %}

```html
<ff-suggest no-auto-highlight>
    <div data-compat-template-role="suggestions">
        <!--
        <section>...</section>
        -->
    </div>
</ff-suggest>
```

{% endtab %}
{% endtabs %}

### `ff-searchbox` properties for Suggest

The `ff-searchbox` element has two attributes which affect `ff-suggest`.

The `use-suggest` attribute determines whether `ff-searchbox` sends *Suggest* requests on input.

With the `suggest-onfocus` attribute, you can define if the *Suggest* opens when the `ff-searchbox` gains focus. Possible values are `"true"` and `"false"` (default is `"false"`).

```html
<ff-searchbox suggest-onfocus="true">
    <input placeholder="Search..." />
</ff-searchbox>
```

For more information see the ff-searchbox page.

### Add Keyboard Support

Keyboard arrow key support is enabled by default.

When a `ff-suggest-item` is selected using the arrow keys, the class `ffw-highlight-suggest-item` is added to its class list. So you simply need to add CSS rules to highlight the selected item.

```html
<style>
    ff-suggest-item.ffw-highlight-suggest-item {
        background-color: lightgray;
    }
</style>
```

### Overriding the default click action

To override the action that happens on click/tap, you can use the `notifications` API of the Web Components core.

```js
factfinder.notifications.addSuggestClickListener(listener);
```

This is the first station in the *Suggest* click pipeline.

In the listener you can perform any task you require and then decide whether you want to resume the pipeline or interrupt it.

You can subscribe multiple listeners. To interrupt the pipeline it is enough if one listener returns `false`.

Note that returning `false` does not prevent subsequent listeners from being invoked. Each click will always invoke **all listeners**.

```html
<ff-suggest no-auto-highlight>
    <!-- content -->
</ff-suggest>

<script>
    document.addEventListener(`ffCoreReady`, ({ factfinder, init, initialSearch }) => {
        // init

        factfinder.notifications.addSuggestClickListener(origin => {
            // `origin` is a reference to the `ff-suggest-item` DOM element that has been clicked.
            // `origin.suggestion` therefore holds a reference to the visualized `ResultSuggestion` as defined by the FactFinder REST API.

            // Perform required tasks.

            // Optionally, return `false` to interrupt the pipeline.
            // return false;
        });
    });
</script>
```

{% hint style="warning" %}
If you are initiating a page navigation from the click-listener, always return `false` to interrupt the pipeline.

This prevents potentially conflicting operations by Web Components as well as unnecessarily invoked requests to FactFinder.
{% endhint %}

### Navigate on click

The expected behavior after clicking on an `ff-suggest-item` element of type `productName` is a navigation to the clicked product's detail page.

`ff-suggest` automatically performs this action if the suggestion data contains a `deeplink` field.

The `deeplink` field is populated with the data from your data feed export column configured with the `Deeplink` field role.

If no `deeplink` is provided for an item of type `productName`, the pipeline will skip this step.

See the *Suggest* click pipeline diagram for a visualization of the exact data flow.

### Closing the Suggest popup

The *Suggest*'s popup automatically closes when the element detects a click that happened outside the popup **and** outside the `ff-searchbox` that triggered the *Suggest*.

Note that custom search boxes are not recognized and clicking into them closes the popup because they are considered "outside".

It does so by adding a click listener to the page's `document` object.

{% hint style="warning" %}
Take care to not prevent the click event from bubbling up to the `document` or the popup will not close.
{% endhint %}

You can **prevent** automatic closing by setting the `hide-onblur` attribute to `"false"`.

```html
<ff-suggest hide-onblur="false" no-auto-highlight></ff-suggest>
```

**Issues with touchpads and other input methods**

Some input devices such as touchpads emit a delayed click event.

If this delay is too long, it can happen that the Suggest closes before your click on a suggestion is registered and nothing happens.

`ff-suggest`'s default delay should be long enough to capture all devices without feeling sluggish.

If, however, your users are still experiencing problems, you can increase the `hide-delay` value until you observe consistent behavior.

See the related API reference.

```html
<ff-suggest hide-delay="350" no-auto-highlight></ff-suggest>
```

### Triggering the Suggest manually

Even though **typically not necessary**, you can invoke Suggest requests via Web Components' JavaScript API as you can with any other request type.

```js
factfinder.request.suggest({ query: `bulldozer` });
```

This request will travel through the request and response pipelines as usual. However, no `ff-suggest` element will react to it.

`ff-suggest` is designed to closely interact with `ff-searchbox` and apply some optimizations.

In order to have `ff-suggest` react to your manual request invocation, you have to supply an `origin` that mimics `ff-searchbox`.

This can be an actual HTML `input` element or an object with a `value` field.

The values of `value` and `query` must match.

```js
factfinder.request.suggest({ query: `bulldozer` }, { origin: document.querySelector(`#my-searchbox`) });

factfinder.request.suggest({ query: `bulldozer` }, { origin: { value: `bulldozer` }});
```

If your `ff-suggest` has the `for-searchbox` attribute configured, you additionally have to specify an `id` on your `origin`.

```js
factfinder.request.suggest({ query: `bulldozer` }, { origin: { value: `bulldozer`, id: `my-searchbox` }});
```

## Demo

Try the [Suggest demo](https://search-web-components.fact-finder.de/demos/4.x/ff-suggest).

## API code

### `ff-suggest`

**Properties**

<details>

<summary>Properties</summary>

| Name                                                                           | Description                                                               |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| **layout** (String) **Options:** `"list"`, `"block"` (default: `"list"`)       | Displays sections as blocks or a vertical list.                           |
| **suggest-items** (Array)                                                      | Data from FactFinder.                                                     |
| **hide-onblur** (String) **Options:** `"true"`, `"false"` (default: `"false"`) | Closes the popup after clicks outside Suggest and the related search box. |

</details>

**Events**

<details>

<summary>Events</summary>

| Name                     | Description                                                      |
| ------------------------ | ---------------------------------------------------------------- |
| **suggest-item-clicked** | Fires when an `ff-suggest-item` is clicked.                      |
| **dom-updated**          | Fires after the element receives data and renders its templates. |

</details>

### `ff-suggest-item`

**Properties**

<details>

<summary>Properties</summary>

| Name                                                                                                        | Description                                |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| **type** (String) **Options:** `"product"`, `"brand"`, `"search"`, `"category"`, `"all"` (default: `"all"`) | The suggest type configured in FactFinder. |
| **suggestion**                                                                                              | Data from FactFinder for one item.         |

</details>

**Events**

<details>

<summary>Events</summary>

| Name              | Description                                |
| ----------------- | ------------------------------------------ |
| **item-clicked**  | Fires when the item is clicked.            |
| **before-search** | Fires before this element starts a search. |

</details>


---

# 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/web-components-4.x./api/basic-elements/suggest.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.