> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# ws-search

> ws-search is the root WebComponent of the search: it initializes the API connection, configuration, and embeds ws-search-box, ws-filters, and ws-search-result.

The `<ws-search>` component establishes the connection between the frontend (search input field, filters) and the search backend. It is required in order to execute search requests and to fetch the data for filters and search results.

## Prerequisite

* The component must be present on every page on which `<ws-search-box>` is used, but only once per page.

## Component

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

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<ws-search
  url="https://<your-shopid>.search.websale.net/api"
  subshop="~WS-SubShopID~"
  {ST-CatPage}category="~CAT-Index~"{/ST-CatPage}                          <!-- WEBSALE V8 syntax -->
  category="{{= $wsViews.current.info.category.id | ifNull('') }}"    <!-- WEBSALE VX syntax -->
  page-size="24"
  default-sort="_score_desc">
</ws-search>
```

<Info>
  Please note: This code example shows both the `category` syntaxes for WEBSALE V8 and VX (as a comment directly after the respective line). Please remember to remove the unused part when using the code.
</Info>

* **Attributes**
  * `url`:
    * Specifies the URL for the API endpoints via which the search requests are executed.
    * Schema: `<your-shopid>.search.websale.net/api`
  * `category`: Category ID (for filtering on a category) – leave empty if you are not on a category page.
  * Use on category pages with the help of [ST-CatPage](https://doku.websale.net/index.html?tag_st-catpage.html) (only for WEBSALE V8)
  * `redirect-url`: Target URL that a search input is redirected to (for example the search result page). For details, see [Redirect to the search result page](#redirect-to-the-search-result-page-redirect-url).
  * `health-check`: Activates a one-time status check of the search backend during initialization. For details, see [Health check on initialization](#health-check-on-initialization-health-check).

## Redirect to the search result page (`redirect-url`)

With the `redirect-url` attribute, `<ws-search>` automatically redirects to the specified target URL on a search input. This is useful on pages that do not display search results themselves (for example landing pages or the home page). The user enters a search term there and is taken directly to the search result page.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<!-- Source code -->
<ws-search
  url="https://test.shop.websale.net/api"
  redirect-url="{{= $wsViews.url('Search', {}) }}">
</ws-search>

<!-- DOM Output -->
<ws-search
  url="https://test.shop.websale.net/api"
  redirect-url="/?wsvc=Search">
</ws-search>
```

**Behavior**

* The redirect only happens if the current page is not already the target page – this prevents a redirect loop on the search result page itself.
* The search term is appended to the target URL as the URL parameter `query`.

**Example**

* On a landing page: search for "laptop" → redirect to `/?wsvc=Search&query=laptop`
* On the search result page: search for "laptop" → no redirect, the search is executed directly

<Info>
  `redirect-url` is available from `ws-search-component-1.9.1.js` onwards and replaces the previous redirect script in the template (event listener on `wsPerformSearch`).
</Info>

## Health check on initialization (`health-check`)

With the `health-check` attribute, `<ws-search>` performs a one-time check of the status of the search backend and the configured indices during initialization. The check is disabled by default. The result is output exclusively in the browser console.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<ws-search
  url="https://<your-shopid>.search.websale.net/api"
  subshop="~WS-SubShopID~"
  health-check="true">
</ws-search>
```

**Behavior**

* When the check is enabled, a request to `<url>/health?subshop=<subshop>` is executed during initialization.
* The console level is derived from the result:

| **Result**                     | **Console output** |
| ------------------------------ | ------------------ |
| All indices OK                 | `console.info`     |
| Individual indices with errors | `console.warn`     |
| No working index               | `console.error`    |

* **Attributes**
  * `health-check`: `true` / `yes` enables the check. Default: disabled.

<Info>
  `health-check` is available from `ws-search-component-1.9.1.js` onwards. The associated API endpoint requires websale\_search version 1.20.1 or higher.
</Info>

## CSS & styling

The component does not generate any additional HTML or CSS code, since it is not a visual component.

Neither CSS adjustments nor HTML elements can be added within the component or through its output.


## Related topics

- [ws-search-button](/en/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/ws-search-button.md)
- [ws-search-result](/en/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/ws-search-result.md)
- [ws-search-box](/en/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/ws-search-box.md)
- [ws-search-info](/en/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/ws-search-info.md)
- [Search & search result page](/en/ws-search/integration-in-die-templates-storefront/suche-suchergebnisseite.md)