Script attributes

All configuration is passed via data-* attributes on the <script> tag. The snippet below is a minimal example — the full list of available attributes is documented in the sections below.

<script
  src="https://search.solosearch.app/widget.js"
  data-engine="your-engine-uuid"
  data-input="#search"
  defer
></script>

Required

data-engine

The UUID of the search engine to use. The snippet generated by the panel already includes this value. You can also find it manually under Search → Search Engines → [your engine] → General.

data-engine="c4b119f6-321e-4268-9d98-8d030f6dfb1a"

The widget will not initialise if this attribute is missing or empty.

Search input

data-input

A CSS selector for the field on your page that drives the search. Defaults to #search if omitted. What it actually does depends on whether the active template set is anchored or an overlay (see Basic Concepts):

  • Anchored template sets — this element is the search box. The widget attaches to it directly and positions results inline below it.
  • Overlay template sets — this element is just the trigger. Focusing or clicking it opens the overlay, which has its own search field built into the template.
data-input="#search"

data-input=".header-search input"

data-input="input[name=q]"

This element must exist on your page — the widget never creates its own trigger.

Appearance

data-locale

Overrides the language used for widget UI strings (e.g. "No results", "Show more", placeholder text). Supported values: en, es, fr, de, it.

data-locale="es"

If omitted, the widget uses the language configured on the engine in the panel (General → Language), which defaults to English.

data-template

Forces a specific template set for this widget instance, overriding whichever one is marked as active for the engine in Design → Template Sets. Takes a template set UUID, shown on its own edit page (Design → Template Sets → [set] → UUID).

data-template="a1b2c3d4-1234-5678-9abc-def012345678"

Useful if you're embedding more than one widget on the same page and want them to look different — each <script> tag can carry its own data-template. Most shops never need this; it's simpler to just set the desired template set as the engine's active one in the panel.

Advanced

data-api

Overrides the API server the widget talks to. Rarely needed: by default the widget derives this automatically from the URL of widget.js itself, so it stays correct even if that URL changes between environments.

data-api="https://search.solosearch.app"

Only set this explicitly if you're intentionally pointing the widget at a different backend than the one serving widget.js — for example, testing against a staging environment.

💡 Minimum characters to search, results per page, facet value limit, and typing debounce are configured in the panel under Design → General → Search Behavior, not as script attributes — see Templates and Design Options.