Getting Started

This guide shows how to add the Cognito Search widget to your site and configure it — including the two render modes: the dropdown search box and the inline search results page.

What you will need

All values are shown in the admin panel under Instances > Embed widget:

• Instance ID — the UUID of your search instance.
• API URL — https://search-dev.k8s-vs.cognito.cz
• Static URL — https://search-dev.k8s-vs.cognito.cz/static

You also need an element on your page where the widget should mount, for example <div id="search-container"></div>.

Direct embed

Add the search widget to your website by including the following script tag and initialization code.

1. Add the script tag to your HTML:

<script src="https://search-dev.k8s-vs.cognito.cz/static/widget.js" data-manual></script>

1. Initialize the widget:

<script>
  window.SearchWidget.init({
    target: '#search-container',
    apiBaseUrl: 'https://search-dev.k8s-vs.cognito.cz',
    instanceId: 'YOUR-INSTANCE-ID',
  });
</script>

Without a mode option the widget renders as a dropdown: a search box that opens a floating results panel as the visitor types.

Embed via Google Tag Manager

Deploy the widget with a single Custom HTML Tag — no code change on your site beyond the mount element. Recommended trigger: DOM Ready – All Pages.

<script>
  (function () {
    window.SearchWidget = window.SearchWidget || {
      q: [],
      init: function (c) {
        this.q.push(c);
      },
    };
    window.SearchWidget.init({
      instanceId: 'YOUR-INSTANCE-ID',
      apiBaseUrl: 'https://search-dev.k8s-vs.cognito.cz',
      staticUrl: 'https://search-dev.k8s-vs.cognito.cz/static',
      target: '#site-search',
      lang: document.documentElement.lang || 'cs',
      dataLayerName: 'dataLayer',
    });
    var s = document.createElement('script');
    s.async = true;
    s.src = 'https://search-dev.k8s-vs.cognito.cz/static/widget.js';
    (document.head || document.documentElement).appendChild(s);
  })();
</script>

Replace #site-search with the CSS selector of your widget container. The snippet queues the configuration before the script loads, so the tag works regardless of load order, and re-fires safely on GTM history changes — the widget mounts only once per element.

Configuration options

¹ target is technically optional, but you should always provide it — and it is effectively required for inline mode, where the results page must render inside a specific page region.

Dropdown mode

The default mode. The widget renders a search input; results appear in a floating panel below it while the visitor types. The panel closes on an outside click or the Escape key.

If you configure a search results page URL in the admin panel (Visual settings > Search results page), pressing Enter in the dropdown navigates the visitor to that page with the query substituted — for example https://shop.example/search?q={query}. The {query} placeholder is replaced with the URL-encoded query. Without a configured URL, Enter simply keeps the dropdown open.

Inline mode — search results page

Inline mode renders a search input plus results as a full-width page region inside your mount element — typically on a dedicated search results page of your site:

<div id="search-results-page"></div>

<script src="https://search-dev.k8s-vs.cognito.cz/static/widget.js" data-manual></script>
<script>
  window.SearchWidget.init({
    target: '#search-results-page',
    apiBaseUrl: 'https://search-dev.k8s-vs.cognito.cz',
    instanceId: 'YOUR-INSTANCE-ID',
    mode: 'inline',
  });
</script>

Inline mode differs from the dropdown in a few ways:

• The results area is always visible — there is no floating panel, no outside-click or Escape close.
• The widget spans 100% of the mount element's width; size it with your own page layout.
• Pressing Enter does not navigate anywhere — results are already on the page.

Running both on one site. The dropdown (e.g. in the site header) and the inline results page can coexist: load widget.js once and call SearchWidget.init twice with different target elements and modes. The same script tag and instance ID serve both.

Result blocks. By default the inline page shows the same result blocks as the dropdown. In the admin panel (Visual settings, tab Inline) you can enable Override default mode visual settings to lay out different result blocks for the inline page; otherwise it inherits the dropdown configuration automatically.

Customizing appearance and behavior

Everything visual is configured in the admin panel under Visual settings — no code changes on your site:

• Result blocks — which sources, banners, and suggested phrases appear, in how many columns (per mode: Dropdown / Inline).
• Style — colors, fonts, sizing applied inside the widget's isolated Shadow DOM.
• Translations — override any widget UI text per language.
• Search results page — the results page URL, how the query is injected ({query} placeholder or a query-string parameter), and whether it opens in a new tab.

Changes are saved as versions; publishing a version makes it live for your embedded widgets immediately.