> 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/basic-elements/searchbox.md).

# Searchbox

A text input that invokes search requests and integrates with \`ff-searchbutton\` and \`ff-suggest\`.

## Documentation

Most basic usage:

```html
<ff-searchbox></ff-searchbox>
```

This setup will render a default `input` element inside and invoke a search request when ENTER is pressed.

By default, it will also send *Suggest* requests when typing. (In order to display the suggestions, an additional [ff-suggest](/webcomponents-overview/api/basic-elements/suggest.md) element is required.)

#### Custom `input` element

You can define your own `input` element with required attributes etc., by placing it into the body of `ff-searchbox`.

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

#### Linking with `ff-searchbutton`

In addition to initiating the search by pressing the ENTER key, you can offer clickable buttons with the `ff-searchbutton` element.

`ff-searchbutton` relies on the current value in `ff-searchbox`. As a page may have multiple search boxes and search buttons, each button needs to know which search box's current value it shall use to invoke a search request from. Therefore, it is necessary to link these two elements explicitly. There are two options to establish this link.

{% hint style="info" %}
Unlike `ff-searchbox`, you always have to specify a `button` element in the `ff-searchbutton`'s body.
{% endhint %}

{% tabs %}
{% tab title="Linking by nesting" %}
By nesting the `ff-searchbutton` inside an `ff-searchbox`, the elements automatically detect their relation.

```html
<ff-searchbox>
    <input type="search">
    <ff-searchbutton><button>Search</button></ff-searchbutton>
</ff-searchbox>
```

{% endtab %}

{% tab title="Linking via attributes" %}
Similar to the native HTML elements `label` and `input` you can define the `id` attribute on `ff-searchbox` and the `for` attribute on `ff-searchbutton` and give them the same value. With this approach the elements' locations in the DOM are irrelevant.

```html
<div>
    <ff-searchbox id="ffSearchBox">
        <input type="search">
    </ff-searchbox>
</div>
<div>
    <ff-searchbutton for="ffSearchBox">
        <button>Search</button>
    </ff-searchbutton>
</div>
```

{% endtab %}
{% endtabs %}

#### Select input value on click

With the `select-onclick` attribute you can define whether the current text should be selected when the search box gets focus. *(default is `"false"`)*

```html
<ff-searchbox select-onclick="true">
    <input />
</ff-searchbox>
```

### Adding Suggest

By default, `ff-searchbox` sends a *Suggest* request every time its text changes and there are at least two characters.

To display the suggestions an `ff-suggest` element is required. Please see [*Suggest*](/webcomponents-overview/api/basic-elements/suggest.md) for information on how to integrate the element.

If you do **not** wish `ff-searchbox` to query suggestions, you can turn this behavior off by setting the `use-suggest` attribute to `"false"`.

```html
<ff-searchbox use-suggest="false"></ff-searchbox>
```

#### Open Suggest on focus

With the property `suggest-onfocus` set to `"true"`, the *Suggest* will open whenever the related search box receives focus.

```html
<ff-searchbox suggest-onfocus="true"></ff-searchbox>
```

**Caching**

When you use `suggest-onfocus="true"`, `ff-searchbox` will cache the last *Suggest* result and reuse it whenever possible.

It will redispatch the result and the related *SuggestParams* through Web Components' [response pipeline](/webcomponents-overview/api/core-api/request-pipelines.md). To pipeline subscribers, such as `ff-suggest` or your custom handlers, it will appear as if a new *Suggest* request has been issued.

However, the *RequestOptions* will be a generic object containing only the `origin` (the `ff-searchbox`). See [RequestInfoSuggest](/webcomponents-overview/api/core-api/type-definitions.md) for data structure.

```js
factfinder.response.transformSuggest((suggestionResult, requestInfoSuggest) => {
    // This transformer would be invoked again when the cached result is redispatched.

    // `suggestionResult`   - The unmodified cached result.
    // `requestInfoSuggest` - Consists of:
    //                        - `suggestParams` from the original request
    //                        - `generic `requestOptions` object
});
```

### Adding Popular Searches

To activate the Popular Searches feature you set the `popular-searches` attribute.

```html
<ff-searchbox popular-searches></ff-searchbox>
```

See the [Popular Searches](/webcomponents-overview/api/more-features/popular-searches.md) article for details.

## Demo

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

## API

### `ff-searchbox` <a href="#ff-searchbox" id="ff-searchbox"></a>

***

#### Properties <a href="#properties" id="properties"></a>

| Name                                                                             | Description                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **popular-searches** (Boolean)                                                   | Setting this attribute activates the Popular Searches feature.                                                                                                                                                                                   |
| **suggest-onfocus** (String) **Options**: "true", "false" (default: "false")     | If this property is set to `"true"`, a FactFinder Suggest recommendation is displayed as soon as the search box is in focus.                                                                                                                     |
| **select-onclick** (String) **Options**: "true", "false" (default: "false")      | Determines if the contents of the search box should be selected if the inside of the box is clicked.                                                                                                                                             |
| **use-suggest** (String) **Options**: "true", "false" (default: "true")          | Determines if a request should be sent to the suggest interface as soon as a user starts typing a search term.                                                                                                                                   |
| **suggest-delay** (Number) (default: 350)                                        | Triggers a suggest request only after the delay expired and no more input is set. When the input field changes within the delay time frame, the delay will reset.                                                                                |
| **show-asterisk-query** (String) **Options**: "true", "false" (default: "false") | Determines if a single asterisk query ("`*`") should be displayed in the component's input field. Does not affect value typed in the field by the user.                                                                                          |
| **value** (String) (default: empty)                                              | Gets or sets the value of the nested HTML `input` element. This property is only accessible through JavaScript. Setting `value` triggers an `input` **event** on the `input` **element**. Therefore, suggestions whill show if they are enabled. |

#### Methods <a href="#methods" id="methods"></a>

| Name                               | Description                                                            |
| ---------------------------------- | ---------------------------------------------------------------------- |
| **search()**                       | Initiates a search with the current search text.                       |
| **resetInput(selector = 'input')** | Tells `ff-searchbox` which nested element it shall use as its `input`. |

### `ff-searchbutton` <a href="#ff-searchbutton" id="ff-searchbutton"></a>

***

#### Properties <a href="#properties" id="properties"></a>

| Name             | Description                                                                          |
| ---------------- | ------------------------------------------------------------------------------------ |
| **for** (String) | Specify the `id` of an `ff-searchbox` element to link the button to that search box. |

#### Methods <a href="#methods" id="methods"></a>

| Name                                 | Description                                                                |
| ------------------------------------ | -------------------------------------------------------------------------- |
| **resetButton(selector = 'button')** | Tells `ff-searchbutton` which nested element it shall use as its `button`. |


---

# 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/basic-elements/searchbox.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.