> For a complete page index of the Captain API documentation, fetch https://docs.captain.dev/llms.txt?excludeSpec=true # Search Widget > Add a search box with instant results to any website with one script tag. > **Note** > > Product Search is in beta with design partners. Endpoints roll out per tenant. `` is a search box for one Product Search index. Results update on every keystroke, matched words are highlighted, and the arrow keys, Enter and Escape work as expected. It runs on any page: plain HTML, React, Next.js, Vue, or a Shopify theme. The widget has no dependencies. For a full search page (facets, sort, pagination), the same file family adds elements that share one search inside ``. See [Search pages](#search-pages). The widget calls the same REST API documented in [Search](/guides/product-search/search) and [Analytics](/guides/product-search/analytics). No SDK is involved. ## Add it to a page Load the script once, then place the element where the search box belongs. ```html ``` `@1.7.3` pins this exact release, and the `integrity` hash makes the browser refuse any other bytes. Each release lists its hashes in `integrity.json` in the [release repository](https://github.com/runcaptain/captain-search). To always get the newest 1.x release instead, load `@1` and leave out `integrity` and `crossorigin`: a moving version cannot carry a hash, and a new release can change the default markup. The box loads recent searches, suggestion, completion and category rows, prices, badges, built image URLs and button render functions from a second file, `captain-search-extras.js`. It fetches the file only when the box needs it: on first focus for the row attributes, as soon as the page loads for `price-field`, `image-template` and `badge-field` (so the first results already show prices), and when a page sets a button render function with `el.templates`. It fetches it from the same exact release on jsDelivr and checks it against a hash built into the box, so the snippet stays one script tag. If your page has a Content Security Policy, allow `https://cdn.jsdelivr.net` in `script-src`. Operators can build this snippet per index in the Product Search console: the tenant's **Integrate** tab, **Embed search**, mints a scoped key locked to your sites and fills it in, for the search box or a full search page. | File | Contains | Size, gzipped | | -------------------------- | ------------------------------------------------------------------- | ------------- | | `captain-search.js` | The search box and `createSearch` | about 13 KB | | `captain-search-extras.js` | Loaded by the box when needed (see above) | about 5 KB | | `captain-instantsearch.js` | The same, plus `` and the search page elements | about 32 KB | In React and Next.js, render the element as JSX and load the script once, for example with `next/script`. The attributes are plain strings. ## Get a browser key The key in the page is visible to anyone who views its source, so it must be a **scoped key** limited to your site. Do not put the search key or the write key in a page. Besides searching, the search key reads the index's analytics, which include what your users search for. A scoped key can search and send events, but it cannot read analytics. Create one on your server with a write key for every index: ```bash curl -X POST "https://acme.captain.dev/v1/keys" \ -H "Authorization: Bearer $CAPTAIN_WRITE_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "scoped", "indexes": ["products"], "filter": {"status": "published"}, "allowed_origins": ["https://www.example.com", "https://example.com"], "description": "website search box" }' ``` The response holds the key once. Copy it into the page. * **`allowed_origins`** lists the sites that may use the key. A browser request from any other site is refused with `403 ORIGIN_NOT_ALLOWED`. List every origin the page is served from, including staging. Origins only bind browsers: a server or script can still send the key, so treat it as public. * **`filter`** is optional. When set, it is applied to every search, and a request can narrow it but never widen it. Use it to say which records the page may show, for example only published ones. Without it, the key reads every record of its indexes. * **`expires_at`** is optional. Without it the key lasts until it is revoked. To rotate a key, create the new one, deploy the page, then revoke the old one with `DELETE /v1/keys/{key_id}`. When records carry access lists (see [Per-record access control](/guides/product-search/search#per-record-access-control)), mint a short-lived scoped key per signed-in user on your server, with the issuer key, and set it from script instead of an attribute: ```js document.querySelector('captain-search').key = keyFromYourServer; ``` ## Attributes | Attribute | Default | Purpose | | ------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `endpoint` | required | The tenant URL from onboarding. | | `index` | required | The index to search. | | `key` | required | A scoped key. Can also be set with `el.key`. | | `placeholder` | `Search` | Placeholder text. Also the accessible name unless `label` is set. | | `label` | none | Accessible name for screen readers. | | `mode` | `dropdown` | `page` shows results under the box instead of in a dropdown, runs a full search on Enter, and pages with a More results button. | | `k` | 8, or 20 in `page` mode | Results per request, up to 50. | | `debounce` | 60 | Milliseconds to wait after a keystroke before searching. Fast typing and pastes send one request. | | `min-chars` | 1 | Characters typed before the first search. | | `filters` | none | Filters for every search, as JSON: `{"category": "shoes"}`. Same syntax as the `filters` search parameter. Can also be set with `el.filters`. | | `title-field` | `title` or `name` | Field shown as the result title. | | `body-field` | `description`, `text` or `content` | Field shown under the title, clipped to two lines. | | `meta-fields` | none | Comma-separated fields shown in small text, for example `brand,price`. | | `image-field` | `image_url` | Field holding a thumbnail URL. | | `image-template` | none | Builds the thumbnail URL from fields, for example `https://img.shop.example/{image_id}/500x500.jpg`. Values are URL-encoded. Falls back to `image-field` when a field in it is empty or the image fails to load. | | `price-field` | none | Field holding the price. Shows a price line under the title. | | `compare-at-field` | none | Field holding the old price. It shows struck through, with the saving, only when it's higher than the price. | | `currency` | none | ISO currency code, for example `USD`. Prices are formatted with `Intl.NumberFormat`. Without it, prices show as plain numbers. | | `locale` | the browser's | Locale for prices, for example `en-US` or `de-DE`. | | `discount` | `percent` | How the saving shows: `percent` (`40% off`), `amount` (`$80.00 off`) or `none`. | | `fraction-digits` | the currency's | `auto` drops the cents on a whole price (`$400`, but `$399.50`), `0` rounds to whole units, `2` always shows two. | | `badge-field` | none | Field shown as a badge above the result title, for example `tag`. | | `sale-badge` | none | Badge text for a result whose old price is higher, for example `Price Drop`. A `badge-field` value wins. | | `completions` | 0 | Up to this many rows that complete the word being typed, above the results. | | `category-field` | none | Field to show category rows for, above the results: its top values for what's typed, counted on the same request. | | `categories` | 3 | How many category rows. | | `category-url` | none | Where a picked category goes, for example `/c/{value}?q={query}`. Values are URL-encoded. | | `url-field` | `url` | Field holding the link a result opens. | | `href-template` | none | Builds the link from fields instead, for example `https://shop.example.com/p/{id}`. Values are URL-encoded. | | `highlight-fields` | engine default | Comma-separated fields to highlight. | | `results-url` | none | Where Enter goes, for example `/search?q={query}`. Without it, Enter runs a full search in place. | | `query-param` | none | On a results page, the URL parameter to read the starting query from, for example `q`. | | `theme` | `light` | `dark`, or `auto` to follow the visitor's system setting. | | `warm` | on | Gets the first search ready before the first keystroke. See [Behavior under load](#behavior-under-load). `warm="false"` turns it off. | | `show-submit` | off | Shows a search button. Without it the magnifier is decoration. | | `show-reset` | on | Shows a clear button while the box has text. `show-reset="false"` hides it. | | `show-loading-indicator` | on | Shows a spinner once a search takes longer than `stall-delay` (200 ms). | | `search-as-you-type` | on | `false` searches only on Enter or the search button. | | `ignore-composition` | off | Waits for IME input (Japanese, Chinese, Korean) to finish before searching. | | `autofocus` | off | Focuses the box when the page loads. | | `render` | shadow | `light` renders into the page instead of a shadow root, so page CSS and `css-classes` style it. | | `css-classes` | none | Extra classes, as JSON: `{"input": "my-input", "submit": ["btn", "btn-primary"]}`. Keys: `root`, `form`, `input`, `submit`, `submitIcon`, `reset`, `resetIcon`, `loadingIndicator`, `loadingIcon`, `panel`, `list`, `item`. Also `el.cssClasses`. | | `analytics` | on | `off` records nothing: no user token, no click events, and searches stay out of the search log. | | `user-token` | generated | The signed-in user's ID for analytics. Without it the widget generates a random token and keeps it in the browser. | Only `http` and `https` links and images are used. Any other URL in a record is ignored. To send requests through your own code, for example to add a header or go through a proxy, set `el.fetch`. It takes the same arguments as `fetch` and must return a `Response`. On a search page, set it on ``, whose search serves every element inside it: ```js const box = document.querySelector('captain-search'); box.fetch = (url, init) => fetch(url, { ...init, headers: { ...init.headers, 'X-Store': 'eu' } }); ``` ### Product dropdown Completion and category rows sit above the products, each group under its own heading. The products show a price, the old price struck through when it's higher, and the saving: ```html ``` Picking a completion searches for it. Picking a category fires `captain-search:category`, then opens `category-url`. Without `category-url`, handle the event yourself. Every row is reachable with the arrow keys. ## Results page A dropdown in the site header can send Enter to a results page, and the results page can show the full list: ```html ``` ## Styling The widget looks finished without any CSS. To match a site, set CSS variables on the element or any parent: ```css captain-search { --cs-accent: #ff6600; --cs-radius: 6px; --cs-font: "Inter", sans-serif; } ``` | Variable | Controls | | -------------------------------------------------- | ---------------------------------------------- | | `--cs-accent` | Focus ring, selected result, highlight tint | | `--cs-bg`, `--cs-fg`, `--cs-muted`, `--cs-border` | Background, text, secondary text, borders | | `--cs-active-bg` | Background of the selected result | | `--cs-radius`, `--cs-shadow` | Corner radius, dropdown shadow | | `--cs-font`, `--cs-font-size`, `--cs-input-height` | Typography and box height | | `--cs-width`, `--cs-max-height`, `--cs-z` | Maximum width, dropdown height, stacking order | For anything else, style the widget's parts with `::part()`: `root`, `form`, `input`, `submit`, `reset`, `loading-indicator`, `panel`, `listbox`, `option`, `link`, `image`, `title`, `body`, `meta`, `mark`, `message`, `more` and `footer`. With `render="light"` the widget has no shadow root: style its `cs-SearchBox-*` classes, or add classes with `css-classes`. Templates replace the buttons and the spinner: `