Add Monocle to any site

What this guide covers

This guide adds Monocle Search to a non-Squarespace site. For a Squarespace site, use the Squarespace setup guide.

Part 1: Create an account

At monocle-search.com, select Register.
Select Register with email and password.
Enter your email address, a password, and the other required details. Then select Create an account.

Select the email and password registration option

Part 2: Set up Monocle

Enter your site URL, then select Start trial. This guide uses demo.monocle-search.com as an example.

Monocle starts to index your site in the background.

Next, copy the script for your site. Your script has a different siteID from the example:

Instructions for adding a script tag to your website

Select the clipboard button, or select and copy the script.

The steps for adding the script depend on your website builder. For a static site generator, such as Jekyll, Next.js, or Astro, add it to the shared layout.

For Cargo Collective, follow the Cargo Collective guide.

If you need help, contact support.

Part 3: Activate the search interface

Use one of these methods to open Monocle Search:

Add a link whose destination is /search.
Add an input with a type of search.

Link to `/search`

The simplest method is a link to /search:

<a href="/search">Search</a>

To open Monocle with a query already filled in, add the preferred mnc-search parameter:

<a href="/search?mnc-search=delivery+times">Search delivery times</a>

/search and ../search links can also use q.

If a link has both parameters, mnc-search takes precedence.

Add mnc-search to any page URL that loads the embed. Search opens with that query when you open or refresh the page.

The following destinations open the same query:

search:delivery%20times
search://delivery%20times
http://search:delivery%20times
https://search:delivery%20times

Style the link to match your site. You can also add a custom SVG icon, such as one from Heroicons.

Add a search input

To add a search input, use this HTML:

<input
  type="search"
  placeholder="Search my site"
  style="width: 300px; border: 1px solid #ccc; padding: 0.5rem; border-radius: 4px"
/>

The search interface then appears like this:

An image showing what the search interface triggered by a search input looks like

Keep a filter input separate

For a filter input, use type="text" without the search-input class. Add data-monocle-ignore to exclude it from automatic search handling:

<input type="text" aria-label="Filter items" data-monocle-ignore>

Set the attribute in the HTML. For script-created inputs, set it before you add the input to the page. You can also set it on a containing element to exclude all inputs inside that element.

Plain text inputs also avoid automatic input detection by older search embeds. Collection inputs use this setup automatically. The autocomplete="off" attribute controls browser suggestions, not the Monocle Search interface.

Install a collection

Collections is available on the free Basic plan. Your site must have beta access.

You can add a collection to any section on an existing page or a new page.

Open Collections in the site menu.
Open a collection.
Open Add to site.
Copy the installation code.

On Squarespace:

Add a Code block where you want the collection to appear.
Select HTML.
Paste the installation code.
Set Display Source to off.

On other sites, paste the installation code into the page HTML at the required position. Do not put it in the page header.

Open Appearance to change the layout and card fields. Drag a field by its dot handle to change its position. You can also focus a field and press Arrow Up or Arrow Down.

Select Platform style under Style to use your site's WordPress or Squarespace styles. WordPress products use WooCommerce markup.

Set Style for items and Control style for search, filters, and sort. The two settings are independent. Select Monocle style to use the built-in design, or Unstyled to write your own CSS. Unstyled keeps the layout, accessible labels, and working controls.

When you select Unstyled, Information for your LLM appears below that selector. Select Copy instructions to copy guidance for a coding agent. It includes the current collection settings, the CSS selectors for this collection, and installation guidance. If both settings are Unstyled, either button copies the same instructions for styling them together. The instructions leave any Platform or Monocle-styled part unchanged.

The preview cannot reproduce styles from your website. Check the collection on your website after installation.

Select 50%, 75%, or 100% above the preview. A lower value shows more content. These controls do not change the collection settings.

Choose content and visitor filters

Content selects the collection. Filters gives visitors choices within that collection. Search lenses do not change a collection.

Unavailable content types are disabled and show an explanation. A plan restriction shows Requires and the available plan names above the disabled feature. Missing content or a content type that is switched off shows a separate explanation, not a plan requirement. If your plan loses a feature, saved selections and card order are kept. Images, product controls, and filter values from unavailable content disappear from the collection. Restoring the feature restores the saved settings.

If none of the selected content types is available, the collection shows no items. You can still change unrelated settings. It does not switch to other content types automatically. If Collections itself is unavailable, visitors see a plan explanation with an administrative login link instead.

Open Content.
Select the content types.
Enter one path or tag rule per line in Content to show.
Open Filters if visitors need choices.
Select Create new filter.
Enter a name in Filter name, as seen by the visitor.
Enter a label in the blank option row.
Type a matching value, then press Enter.
Select Add option if visitors need more choices.
Check Filter preview.
Select Done to close the filter editor.

The value in Filter name, as seen by the visitor appears above the options on your website. Use Internal name (optional) to distinguish saved filters in the editor. For example, two filters can show Categories to visitors. Use Blog categories and Shop categories as their internal names. Select the appropriate filter for each collection.

Without an internal name, the editor uses the visitor name. Each saved filter must have a different name in the editor. Internal names are not shown to visitors or used by AI answers.

For example, /blog/* includes items under /blog/. The rule tag:News includes items with the News tag. Use /* to include all content. An empty field shows no items.

In Content to show, put ! before a rule to exclude matches. For example, combine /blog/* with !tag:Archived. This includes blog pages but excludes items with the Archived tag. Exclusions override inclusions in this mode. Exclusion rules alone show no items.

Select Show instructions for path and tag examples. The examples use the current rule mode.

Content to show suggests available indexed paths and tags. The filter table suggests available indexed values and counts matching items in this collection. Options with no available source values are hidden from visitors, but their saved definitions are kept. An option available elsewhere on the site can remain visible with no matches in this collection.

One filter option can match several source values. Use the Match menu for starts-with, contains, or advanced wildcard rules. In Advanced wildcard pattern, use * to match any text, \* for a literal star, and \\ for a literal backslash.

Suggestions hide exact values already added to the current option. Remove a value to make it available again. You can still use the same value in another option.

Values such as Medium: Ink and Medium: Pencil create an automatic Medium filter. A prefix must have at least two different options. Automatic options stay in sync with indexed content. Turn on its switch in Filters to use it in this collection.

The filter list shows each filter's name, option count, and example labels. Also used on links to the Filters section of other collections in new tabs. Use a filter's switch to enable or disable it in this collection. Drag the dot handle to reorder filters, or focus the handle and press Arrow Up or Arrow Down. Select Edit to change a filter's labels and matching values.

Each collection keeps its own order. Switching a filter off leaves it in place. You can reorder disabled filters and switch them back on without losing their positions.

Turn off Show visitor filters to hide the filter settings. Your filter selections and placement are kept when you turn it back on.

Product specific filters is disabled when Products is switched off under Content, or product search is unavailable on your plan. Your product filter settings are kept.

Select Suggest filters beside Create new filter to find additional custom filters. AI uses currently available content and filter values. It considers existing available filters, including those switched off in this collection, to avoid duplicate groupings. Automatic prefix filters are excluded. A loading card appears below the list, then becomes a review. Review each filter name, option label, and matching value, then select Apply suggestions. Cancel closes the card and restores Suggest filters.

Drag a row handle to reorder options, or use Move up and Move down in its menu. Tab moves across inputs. Up at the start of an input and Down at the end move between rows.

The normal collection preview stays visible while you choose filter placement. Editing a filter replaces it with Filter preview, which names the current collection. Choose options to see matching content from that collection. Select an item count to inspect an option's matches. Done or Cancel restores the normal preview with its search, sorting, and remaining filter selections.

Display-only changes keep the current preview session, including the visitor's search and filter choices.

Select Use Search Lens rules to use the same rule behaviour as Search lenses. In that mode, a rule excludes matches. Add ! to include matches. Inclusions override exclusions.

Valid changes save automatically and update the website. Invalid changes do not replace the saved settings. Done closes the filter editor. Cancel removes only unsaved filter edits. Reset unsaved changes restores the latest saved settings. For a new filter, reset is available only after its first successful save.

A saved filter definition can be used by several collections. Editing that definition changes every collection that uses it. Turning off a filter in one collection does not delete the definition.

Used in collections lists the collections that use the filter. Select a collection name to open its Filters section. Other collections open in a new tab. To delete a custom filter from every collection, select Delete filter below this list. Check the affected collections in the confirmation dialogue, then select Delete filter everywhere. Other filter definitions are not changed.

Saved filter definitions also help AI answers interpret indexed values. They do not automatically restrict answers or add filters to regular search.

Collection controls update the page URL automatically. The URL stores the query, selected filters, price range, sort order, and page.

Copy the URL from your browser's address bar to share it. Opening or refreshing that URL restores the settings. Collections with infinite scroll restore up to 20 previously loaded pages. You can continue scrolling to load more.

Each collection on the page keeps separate settings. Closing search does not clear the collection settings. The results can change when your site's content changes.

These URLs apply to public collections, not admin previews.

Programmatic activation

Developers can also activate Monocle Search programmatically.

The script exposes the Monocle object on window. Contact support if you need help with this API.

For example, this code uses an input with the ID search and renders results in an element with the ID results:

<script type="module">
  let monocleReady = false;

  function tryInitialiseSearch(input) {
    const mount = document.getElementById("results");
    if (!mount || !window.Monocle)
        return false;

    window.Monocle.createCustomInterface(input, mount);
    return true;
  }

  function handleFocus(event) {
    const {target} = event;
    if (monocleReady || target.id !== "search")
        return;

    try {
        monocleReady = tryInitialiseSearch(target);
        if (monocleReady)
            document.removeEventListener("focusin", handleFocus);
    } catch (err) {
        console.error("Failed to initialise Monocle Search:", err);
    }
  }

  document.addEventListener("focusin", handleFocus);
</script>

Part 4: Customise Monocle Search

Use the design and page exclusion editors in the Monocle admin interface to customise search.

Shows where to find the design and exclusion editors

Manage your sites

If your account has more than one site, select the site title in the top bar. Then select another site from the menu.

The top bar also contains All sites, Documentation, Billing information, Account settings, and Log out.

On a small screen, open the navigation menu at the top right to find these account controls. Use Site menu to find settings for the current site.

Get help

Contact support if you cannot complete a step or need help with a custom setup.