> For the complete documentation index, see [llms.txt](https://docs.codegiganten.de/plugin-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/search-in-the-shop.md).

# Search in the shop

How the search looks and behaves in your shop: activation, search window, suggestions, results, layouts, product card, filters and keyboard.

This page describes the search from your customers' point of view. It shows what a visitor sees and can use, and for each point it names the setting that controls it. You find all settings in the plugin configuration on the card "Search configuration", and you can maintain them per sales channel.

## When the search is active in the shop

The InsightSearch search window only appears if two things are true:

1. "Enable search" is switched on (default: off).
2. A search index is assigned for the combination of sales channel and language (assignment in the plugin dashboard under language mapping).

If the assignment is missing for a language, the Shopware search stays unchanged in that language, without a message. The same applies to the layout "Native Shopware design": there is no plugin window then, but the results still come from InsightSearch (see the layouts below).

## Activation modes

With "Search activation mode" you decide how the search window opens. The default is "Use Shopware standard search field".

<figure><img src="https://923488348-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FebcjSiStaIxyVJ83vjsL%2Fuploads%2Fgit-blob-28ddd0e7332e8109b4ecbe1f1a38b23ee98f9dca%2Fimage%20(93).png?alt=media" alt="Selection of the search activation mode"><figcaption></figcaption></figure>

| Mode                                 | What happens                                                                                                                                                                               | When it makes sense                                                               |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| "Use Shopware standard search field" | The plugin attaches to the search field in your theme's header. The window opens as soon as the customer clicks into the field or types. Shopware's own suggestion window is switched off. | The normal case, if your theme has a regular search field.                        |
| "Search field always visible"        | The plugin creates its own search field with a magnifier button. It opens on click or typing, like the standard mode.                                                                      | If the theme has no suitable search field.                                        |
| "Activate via external trigger"      | The window opens when the customer clicks an element that you name in the "Trigger selector".                                                                                              | If the theme builds the search differently, for example with its own search icon. |
| "Activate via search button"         | Like the standard mode; in addition, a click on the magnifier opens the window instead of submitting the form.                                                                             | For themes where the search field is not permanently on the page.                 |

### The external trigger

In the field "Trigger selector" you enter a CSS selector, that is the name of the element that should open the search. A class name needs a dot in front, an ID needs a hash sign, for example `.my-search-button` or `#open-search`.

* A click on the element opens the window and puts the cursor into the search field. The element's own action (for example a link) is suppressed.
* Another click on the trigger closes the window again.
* Triggers that are loaded later also work.
* If the field is empty, nothing opens.

### What happens on Enter

This depends on two switches in the area "Search results page and variants":

* **Both off (default):** Enter leaves the results in the window. Below the minimum number of characters a hint appears, with an empty field the empty state. If the term has a redirect from the search term rules, the customer is redirected.
* **"Allow redirect to Shopware search results page on Enter" or "Deliver Shopware search results page via InsightSearch":** Enter opens Shopware's search results page. If an entry is marked with the arrow keys, that entry is opened instead.

Read more about the results page under [Search results page](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/search-results-page.md).

## Layout of the search window

The window fills the screen. The background is dimmed and the page behind it no longer scrolls. From top to bottom the customer sees:

1. **Header:** search field with a cross (clears the text) and a magnifier, next to it the close button. From 768 pixels width, your shop logo appears on the left.
2. **Suggestions:** the heading "Suggestions" with selection buttons, one button per suggested term.
3. **Active filters:** only if filters are selected, with "×" and the link "Reset".
4. **Content:** the filter sidebar "Filters" on the left (from 992 pixels width), the results on the right. Without enabled filters the results use the full width.
5. **Results:** a heading such as "Products (128 results)", below it the product cards in the chosen layout.
6. **End:** the button "Load more results", followed by "Goes with …" and "You might also like" where applicable.

### Closing

The window closes with the close button, with the Esc key, with a click on the dimmed edge, and when the focus leaves the window, for example by a click on another element of the page. The text in the search field is kept.

{% hint style="info" %}
Cookie banners, chat windows and other pop-ups that grab the focus on loading can close an open search window. If you notice this, check these elements first.
{% endhint %}

### Input and minimum characters

Suggestions appear from 1 character. Product results appear from the "Minimum number of characters for search" (default 3, smallest value 1). If the input is shorter, the results area shows "Please enter at least 3 characters." (with your configured number). "Popular searches" and "Recent searches" bypass this limit.

If a request takes longer than 8 seconds, "Failed to load results." appears. The rest of the page stays usable.

## The empty state

If the customer opens the search without typing anything, the window shows:

* **"Recent searches"** (with a clock icon): at most 3 terms from this browser tab, visible immediately. With "Hide history" the list disappears for this tab.
* **"Popular searches":** up to 10 terms that are often searched in your shop. If there are no recent terms, the heading reads "Suggestions".

If there is nothing to show, the window stays closed when the customer clicks into the empty field, so that no empty full-screen window hangs around. If it is forced open by Enter, the magnifier or a trigger, it says "Please enter a search term."

If you want to design the empty state yourself, choose a shopping experience at "CMS page for empty search state". It appears in the window, with the terms next to it. With a page selected, the window also opens when there are no terms. Compact banners, entry points to categories, promotions or a bestseller slider work well. More under [CMS elements and recommendations](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/cms-elements-and-recommendations.md).

## Suggestions

The suggestions appear as selection buttons above the results. You set the number with "Number of search suggestions" (1 to 10, default 5).

* Every entered word (from 2 characters) is shown in bold within the suggestion.
* If the system detects a typo, the correction appears as an additional suggestion in the accent colour.
* A click on a suggestion puts it into the field and starts the search. Some suggestions bring a filter with them, for example a brand. It is then set directly, as long as filters are enabled.

## Results and loading more

You set the number of results per request with "Number of search results (per page)" (default 12). The heading shows the total.

If "Enable pagination for search results" is on (default), the button "Load more results" appears at the bottom. While loading it reads "Loading results...", at the end "No more results". Loaded results are appended; search term, filters and scroll position stay. If the option is off, customers only see the first page. In the carousel there is no button; the window loads more when the customer swipes to the right end.

## Layouts

The "Search popup layout" decides how the products are arranged. The default is "Grid with detailed cards (default)".

| Layout                                                     | Appearance                                                                                                                                                                                 | Recommendation                                                                                                               |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| "Grid with detailed cards (default)"                       | Large images, badges, name, subtitle and prices. About 4 columns on desktop, 2 on tablets; on phones it becomes a list.                                                                    | The normal case, especially for fashion, lifestyle and image-driven ranges. Only here you get badges and subtitles.          |
| "Compact list"                                             | One row per product: small image on the left, name and price next to it. No badges or subtitles.                                                                                           | Technical shops with long names, spare parts, many results in little space.                                                  |
| "Compact grid"                                             | Denser than the grid: about 3 columns from tablet, up to about 6 on desktop. No badges or subtitles.                                                                                       | Large ranges with little text, quick overview.                                                                               |
| "Carousel"                                                 | One horizontal row with arrow buttons, swipeable. The window stays low, more results load at the right end.                                                                                | A few high-quality results.                                                                                                  |
| "Native Shopware design (InsightSearch results, no popup)" | No plugin window. Shopware's suggestion window stays, with your theme's design; results and order come from InsightSearch. If InsightSearch is unreachable, Shopware's own results appear. | Themes with a heavily customised header where the window does not fit, or if you only want to swap the order of the results. |

With the layout "Native", filters, quick view, cart button, badges and all other window settings have no effect. Additional lists such as "You might also like" or replacement products always use the standard card.

**Our recommendation:** Start with the standard grid. Switch to the compact list if your product names are long or images say little, and to the native design only if the window does not work cleanly in your theme.

How the search looks on a phone is described under [Search on mobile](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/search-on-mobile.md).

## The product card

### Image and replacement image

The card shows the product image. If it is missing or does not load, the "Image for products without an image" appears, which you choose from your Shopware media (per sales channel). The replacement image also applies to replacement products and in the shopping assistant, and Cross-Selling Pro uses it too if none is maintained there. Without a selection, a grey placeholder appears. On the Shopware search results page, Shopware shows its own display.

### Name and subtitle

The whole card is clickable; a click with the middle mouse button opens the product in a new tab. The subtitle comes from the "Subtitle configuration" per search index (see [Language mapping and subtitle](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/general-settings.md)). "Position of the subtitle" is "Above the product name" or "Below the product name" (default). Several values are joined with a comma. The subtitle only appears in the grid.

### Prices

* The normal price appears in the currency of the sales channel. If the strike price differs, it appears crossed out in front. If variants have different prices, "from " is shown in front.
* "Hide prices in search" (default off) hides all prices on the cards, including the base price.
* "Show prices with UVP prefix" (default off) puts "UVP " (recommended retail price) in front of the price.
* "Show base prices and units in search" shows, for example, "€12.50 / 1 kg" below the price if package unit and reference unit exist.
* "Show live prices from Shopware (Beta)" (default off) loads the real, customer-specific price for every visible product, for example from advanced price rules, and shows it in Shopware's own price display. This costs one extra query per search. Together with "Hide prices in search" or the UVP prefix, the function is not active.

{% hint style="info" %}
Without live prices, the card shows the price from your product data. It can differ from the price in the shop if there are customer-specific prices or the data has not been re-read yet.
{% endhint %}

### Badges

With "Show badges on search result cards" (default off), up to 2 coloured labels appear at the top left of the image. Title and colour come from the data field "badge", which you define under [Edit data fields](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/feed-template-editor.md).

### Quick view

"Enable quick view on search result cards" (default off) places a round eye button at the top right of the image. It opens Shopware's quick view above the search window without leaving it.

### Cart button

"Add-to-cart button in the search overlay" (default off) places a round cart icon at the bottom right of the card:

* **Simple, available products:** One click puts 1 item into the cart, the window closes and the side cart opens.
* **Products with variants:** The button reads "Choose options" and opens the quick view if it is active, otherwise the product page.
* **Sold-out products:** no button.

The button also works for "Goes with …" and for replacement products.

## Filters in the search window

Filters are off by default. Switch on "Enable filter rendering" so that the sidebar, active filters and filter buttons appear. You decide which filters exist in the plugin dashboard under [Filters](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/filters.md). Changes there are visible in the shop after up to 5 minutes.

* **List filters:** selection buttons with label and number of results. Several values of a group can be chosen; each click switches on or off.
* **Range filters** (for example price): a slider with two handles, number fields "from" and "to", both, or price steps such as "up to €20". A new search runs after releasing the handle, not at every intermediate step. A filter with only one value is hidden.
* **Step slider** for text values such as sizes (S, M, L).

**Expanding and collapsing:** "Default filter group state" is "Open (all expanded)" (default) or "Closed (all collapsed)". The filter maintenance can override this per filter. Groups with selected values are always open. A click on the group heading expands or collapses it.

**Show more:** "Visible options per filter" (default 5, allowed 1 to 50). Further options appear via "Show more", then "Show less".

**Active filters:** Selected filters appear at the top, for example "Price: €10 to €50", with "×" to remove them, and the link "Reset" on the right. A new search term resets the filters.

Phones have their own rules, see [Search on mobile](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/search-on-mobile.md).

## Keyboard

* **Arrow down and up** jump through suggestions, products and filter options; at the end it continues in a circle.
* **Enter** opens the marked entry. Without a marked entry, the behaviour from the section "What happens on Enter" applies.
* **Esc** closes the window.
* **Tab** and **Shift+Tab** stay inside the window. This helps screen reader users.
* All buttons carry labels for screen readers, for example "Add to cart".

## Restore when going back

If a customer opens a product from the search window and goes back in the browser, the window opens again in the same state. "Restore search when going back" is on by default.

* **What is remembered:** search term, selected filters, the number of loaded pages (up to 5) and the scroll position.
* **Validity:** 30 minutes, in the same browser tab.
* **Not restored** if the customer closed the window themselves, switched to the search results page with Enter, a redirect applied, the page was reloaded, or more than 30 minutes have passed.
* On touch devices the on-screen keyboard does not open by itself.
* Restored requests do not count as a new search in the statistics.

## Banners and redirects

With the [search term rules](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/search-term-rules.md) (paid add-on) you control individual terms:

* **Banner:** A shopping experience appears above the results, in the window as well as on the results page. This also applies if the term has no product results.
* **Redirect:** It applies on submitting (Enter or magnifier), not while typing. Allowed targets are relative paths, the domains of the sales channel and domains that you enter under "Allowed external hosts for search term redirects" (one per line). Other targets are ignored and the page loads normally.

## "Goes with"

If "Cross-Selling Pro - KI Cross Selling" is connected in the same shop, the window shows "Goes with …" below the results, with the name of the first result and up to 4 matching complementary products. The switch is called "Goes with" in the search overlay and is on by default. Without Cross-Selling Pro nothing changes. Details are on the page [CMS elements and recommendations](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/cms-elements-and-recommendations.md).

## Texts and languages

All texts in the window come from Shopware snippets. German and English are included. You create your own wording in Shopware under Settings → Shop → Snippets. The snippets of this plugin start with `cogi-insightsearch.storefront.`. How to set the placeholder in the search field per language is described under [Customize design](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/customize-design.md).

## If the search does nothing

Check in this order:

1. Is "Enable search" on?
2. Is a search index assigned for the language?
3. Is the layout set to "Native Shopware design"? Then there is no window.
4. Does the activation mode fit your theme? With heavily customised themes, "Activate via external trigger" or "Activate via search button" help.
5. Does a security policy or an ad blocker block the request? Then "Failed to load results." appears.

More help is on the page [Troubleshooting](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/troubleshooting.md).

## Read on

{% content-ref url="/pages/ONADSPn6JKPHifT1E0iD" %}
[No results](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/no-results.md)
{% endcontent-ref %}

{% content-ref url="/pages/ZAzWWbWk8mnvP2MvrZ1T" %}
[Search on mobile](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/search-on-mobile.md)
{% endcontent-ref %}

{% content-ref url="/pages/SX6VJJikEcgYUirKdc6e" %}
[Customize design](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/customize-design.md)
{% endcontent-ref %}

{% content-ref url="/pages/v20EC98NJrD47BUleH4w" %}
[Plugin settings](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/plugin-settings.md)
{% endcontent-ref %}


---

# 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.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/search-in-the-shop.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.
