Documentation

Everything you need to embed semantic search on your site.

What is Semantic Search?

Semantic Search is an embeddable widget that adds natural language search to any website via a single <script> tag. Instead of matching exact keywords, it ranks results by meaning.

The widget works on plain HTML pages as well as Single Page Application frameworks such as React. It comes with workable defaults so you can add in with no configuration, and exposes data-* attributes for more control over markup, behaviour, and the optional AI-generated summary shown above results.

Quick start

Add a mount point and load the script. The widget auto-initialises on page load.

<div class="ssw-search"></div>
<script src="https://api.search.tomfox.tech/widget/v1.js?site=public_key"></script>

The site query parameter is the public site key from your dashboard.

Modes

The widget supports two embed modes: full, where the widget renders its own form and results, and results-only, where you provide the form markup and the widget renders only the results list.

Full widget

<div class="ssw-search"></div>
<script src="https://api.search.tomfox.tech/widget/v1.js?site=public_key"></script>

Results-only

<form class="ssw-form">
  <input class="ssw-input" type="search" placeholder="Search articles" />
  <button class="ssw-button" type="submit">Search</button>
</form>

<div class="ssw-results"></div>

<script
  src="https://api.search.tomfox.tech/widget/v1.js?site=public_key"
  data-mode="results-only"
></script>

If the default class names do not fit your markup, any selector can be overridden via a data-* attribute. See Configuration.

Configuration

Every option below maps to a data-* attribute on the <script> tag. Do not include any attribute to use its default.

Attribute	Default	Description
data-mode	"full"	Either "full" or "results-only".
data-placeholder-text	"Search..."	Input placeholder text (full mode).
data-open-in-new-tab	"true"	Open result links in a new tab.
data-debounce-ms	"300"	Milliseconds between keystroke and sending a request. Set to 0 to disable.
data-idle-text	none	Text shown before any search has been run.
data-loading-text	"Searching..."	Text shown while a request is in progress. Set to an empty string to hide it.
data-no-results-text	"No results found."	Shown when the response contains no results.
data-summary-enabled	"false"	Enable the AI-generated summary above results.
data-container-selector	".ssw-search"	Location for the widget (full mode).
data-results-selector	".ssw-results"	Results container (results-only mode).
data-form-selector	".ssw-form"	Form element (results-only mode, optional).
data-input-selector	".ssw-input"	Search input (results-only mode).
data-button-selector	".ssw-button"	Submit button (results-only mode, optional).

Custom selectors

When you cannot use the default class names, configure the widget to use your own elements with the selector attributes.

<form id="docs-search-form">
  <input id="docs-search-input" type="search" />
  <button id="docs-search-button" type="submit">Search</button>
</form>

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

<script
  src="https://api.search.tomfox.tech/widget/v1.js?site=public_key"
  data-mode="results-only"
  data-results-selector="#docs-search-results"
  data-form-selector="#docs-search-form"
  data-input-selector="#docs-search-input"
  data-button-selector="#docs-search-button"
  data-debounce-ms="200"
></script>