Visual Search widget

Overview

The Visual Search widget gives shoppers three ways to discover products:

Image search modal: shoppers upload an image or select an area of an image to find visually similar products.
Shop-similar modal: shoppers open a product-specific view of similar products.
Similar-products preview: you can display a product grid directly on a page and let shoppers open the full modal.

The widget is a standalone JavaScript module served from the Layers CDN. The Layers app embed does not load it. The embed writes the storefrontApiToken that the widget can use and loads the storefront pixel, which forwards widget events to Clarity or Blotout when those integrations are enabled. Add the widget script to your theme yourself. See What the app embed handles.

Prerequisites

Install Layers and enable the app embed if you want it to provide the storefront access token and forward widget events.
Have a storefront access token available. When the app embed is enabled, the widget can read its storefrontApiToken automatically. You can also provide a token on the widget script or through the widget manager.
Add the widget script to your Shopify theme. Enabling the app embed alone does not add the widget.

Installation

Add the script to layout/theme.liquid, before the closing </body> tag:

<script
  id="layers-script"
  type="module"
  src="https://cdn.uselayers.com/widget/layers-widget.js"
></script>

The CDN build is an ES module, so use type="module". Module scripts defer automatically; you do not need to add defer. Once the script loads, you can add the custom elements where you want the entry points and preview to appear. See Image search, Shop similar, and Similar-products preview.

Script attributes

Put these attributes on the script element with id="layers-script".

Attribute	Type and values	Default	Description
`data-api-key`	String	No value	Storefront access token. If present when the widget initializes, it becomes the configured key. If no key was configured at initialization, the widget also checks the current attribute value for each API request.
`data-hide-branding`	String: `"true"`	Unset	Set to `"true"` to hide the Powered by Layers footer in the image-search and similar-products modals. A boolean `hideBranding` value set through `configure()` overrides this attribute.
`data-debug`	String: `"true"` or `"false"`	`"false"`	Enables widget debug logging when the script initializes. The widget reads this attribute at initialization; use `configure({ debug: true })` to change debug logging later.

API key resolution and load order

The widget resolves its access token whenever it makes an API request, in this order:

widgetManager.config.apiKey, set with setApiKey(), configure({ apiKey }), or by a non-empty data-api-key value read when the widget initializes.
The current non-empty data-api-key value on #layers-script.
The storefrontApiToken value in the app embed’s <script id="layers-config" type="application/json"> element.

If you inject data-api-key after the widget loads and no key was configured at initialization, the widget can use the new value on its next request. A key already stored in config.apiKey remains higher priority than later changes to the attribute. The widget caches the app embed token after it first parses a valid value. Missing or invalid embed JSON does not prevent initialization. data-debug is read once when the widget initializes. In contrast, data-hide-branding is checked when each modal renders, unless you explicitly configure hideBranding.

JavaScript configuration

The widget manager is available at window.Layers.widgetManager. Configure it after the module has loaded:

<script>
  document.addEventListener('DOMContentLoaded', () => {
    window.Layers.widgetManager.configure({
      debug: false,
      showInstructions: true,
      hideBranding: true,
      currencyFormat: {
        currency: 'EUR',
        locale: 'de-DE'
      }
    })
  })
</script>

configure() accepts these options:

Option	Type	Default	Description
`apiKey`	String	Unset	Sets the highest-priority storefront access token.
`debug`	Boolean	`false`	Enables or disables debug logging.
`showInstructions`	Boolean	`true`	Shows or hides the image-search instructions by default.
`hideBranding`	Boolean	Unset	When set, overrides `data-hide-branding` for both modals.
`currencyFormat`	Object	See below	Sets price formatting. `configure()` merges this object with the existing currency format instead of replacing it.
`translations`	Object keyed by `"image-search"` and `"similar-products"`	Unset	Overrides widget copy. Each value is deep-merged over that widget’s built-in text. See Translations.

The currencyFormat object accepts:

Property	Type and values	Default	Description
`currency`	ISO currency code, such as `"EUR"`	Unset	Explicit currency override.
`locale`	Locale string, such as `"de-DE"`	Unset	Explicit locale override.
`style`	`"currency"` or `"decimal"`	`"currency"`	Selects currency or decimal number formatting.
`currencyDisplay`	`"symbol"`, `"code"`, or `"name"`	`"symbol"`	Controls how the currency appears when `style` is `"currency"`.
`showSymbol`	Boolean	`true`	Legacy configuration field. The current formatter uses `currencyDisplay` to choose the currency representation.

For example, configure({ currencyFormat: { currency: 'EUR' } }) keeps the default style: 'currency' and currencyDisplay: 'symbol'. You can also use updateCurrencyFormat() to merge currency-format properties. Other available methods include:

setApiKey(apiKey) and getApiKey() to set or resolve the storefront access token.
createImageSearchToggle(options), createSimilarProductsToggle(options), and createSimilarProductsPreview(options) to add widgets from JavaScript.
updateTheme(properties) to set CSS custom properties at runtime.
updateTranslations(widgetType, translations) to merge translations for image-search or similar-products.
debugTheme() to log the theme values the widget manager tracks.

Image search toggle

Use <layers-image-search-toggle> to add a button that opens the image-search modal.

<layers-image-search-toggle
  upload-mode="drag-drop"
  icon="CameraSearch"
  tooltip-enabled="true"
  tooltip-text="Search with an image"
></layers-image-search-toggle>

Attribute	Type and values	Default	Description
`template-id`	String	Unset	ID of a `<template>` whose contents appear in the upload step.
`upload-mode`	`"drag-drop"` or `"button"`	`"drag-drop"`	Selects the drag-and-drop upload area or the upload button. Any value other than `"button"` uses drag-and-drop mode.
`icon`	`"ScanSearch"`, `"Search"`, `"Camera"`, or `"CameraSearch"`	`"ScanSearch"`	Chooses the toggle icon.
`show-instructions`	String: `"true"` or `"false"`	`true`	Shows or hides the image-search instructions.
`enable-paste`	String: `"true"` or `"false"`	`false`	Set to `"true"` to enable pasting an image.
`tooltip-enabled`	String: `"true"` or `"false"`	`true`	Set to `"false"` to disable the tooltip.
`tooltip-text`	String	Built-in translation: `"NEW: Search with your camera"`	Sets the tooltip text.
`tooltip-duration`	Integer, milliseconds	`15000`	Sets how long the tooltip stays visible.
`tooltip-max-shows`	Integer	`15`	Sets the maximum number of tooltip displays for the current session.
`tooltip-show-close-button`	String: `"true"` or `"false"`	`true`	Set to `"false"` to hide the tooltip’s close button.
`translations`	JSON string	Unset	Copy overrides for the modal this toggle opens, in the same shape as the `image-search` translations. See Translations.

Both toggles show a pointer cursor on hover. The widget sets it with a zero-specificity rule, so any cursor rule in your theme CSS wins. When an image search returns results, the widget adds the uploaded image ID to the page URL as ?layers_image_search=<id>. It uses history.replaceState, so it keeps your existing query parameters and does not add a history entry. It also saves a smaller copy of the shopper’s photo (up to 1000px) in the browser’s sessionStorage for the current tab. When a shopper opens a product from the results and presses Back, the first <layers-image-search-toggle> on the page reopens the modal. Before searching, the widget requires a matching image ID in the current tab’s sessionStorage. With that saved state, it searches again without uploading the photo a second time. The saved copy restores the photo preview and the Crop Image button. A URL image ID alone cannot restore results.

Missing saved state: if storage is missing, blocked, full, or contains a different image ID, the widget removes the URL parameter and stays on the upload step without searching. A new tab usually has separate storage, but a tab opened from another tab can receive a copy of its opener’s sessionStorage and restore matching state.
Expired image ID: Layers keeps an uploaded image for about one hour. After that, the widget uploads the saved copy again and shows fresh results. If the matching stored state has no image copy, the widget removes the parameter and shows the upload step.
Temporary errors: network errors, rate limits, and server errors keep the image ID in the URL and show the error state, so Retry runs the same search.
Clearing: closing the modal, starting a new search, or going back to the upload step removes the parameter and the saved copy.
Client-side navigation: if your theme re-renders the toggle when the route changes, the new toggle restores the search too. Only one toggle restores at a time, so pages with several toggles open one modal.

You don’t need to change your theme for this. It works as soon as the toggle is on the page the shopper returns to.

Custom upload content

Add a <template> and reference its id with template-id to display custom content in the upload step:

<template id="image-search-upload-tips">
  <div>
    <p>Choose a photo or paste an image to find similar products.</p>
  </div>
</template>

<layers-image-search-toggle template-id="image-search-upload-tips"></layers-image-search-toggle>

Reference images and area-selection events

Use <layers-image-search-reference-image> to open image search from an image:

<layers-image-search-reference-image
  src="/files/product-inspiration.jpg"
  alt="Search with this image"
></layers-image-search-reference-image>

The custom element copies its attributes to an image and opens the search flow when a shopper clicks it. The widget also emits a bubbling layers-image-search-area-selected event after the shopper selects an image area:

<script>
  document.addEventListener('layers-image-search-area-selected', (event) => {
    console.log('Selected image area:', event.detail)
  })
</script>

Similar-products toggle

Use <layers-similar-products-toggle> to add an entry point for a product’s similar-products modal:

<layers-similar-products-toggle product-id="{{ product.id }}"></layers-similar-products-toggle>

Attribute	Type and values	Default	Description
`product-id`	String	Required	Product ID used to find similar products.
`reference-image-src`	String URL	Unset	Shows a reference image in the modal.
`data-facet-code`	String	Unset	Requests and displays facet options for the specified facet.
`data-filter-options`	JSON string	Unset	The toggle parses and forwards an array of objects with a `title` and an `options` array; each option has a `name` and `value`. The current modal does not read this attribute, so it does not change the displayed filters.

You can add a filter group as a child script. The widget validates this JSON before using it:

<layers-similar-products-toggle product-id="{{ product.id }}">
  <script type="layers/filter-groups">
    {
      "conditional": "AND",
      "expressions": [
        {
          "property": "price",
          "operator": "greater_than",
          "values": [50]
        }
      ]
    }
  </script>
</layers-similar-products-toggle>

Set conditional to "AND" or "OR". Each expression has a string property, a string operator, and a values array containing strings, numbers, or booleans.

Similar-products preview

Use <layers-similar-products-preview> to render a product grid with a button that opens the similar-products modal:

<layers-similar-products-preview
  product-id="{{ product.id }}"
  limit="4"
  lazy-load="true"
></layers-similar-products-preview>

Attribute	Type and values	Default	Description
`product-id`	String	Required	Product ID used to find similar products.
`lazy-load`	String: `"true"` or `"false"`	`true`	Loads results when the preview approaches the viewport. Set to `"false"` to load immediately.
`limit`	Integer	`4`	Number of products to show in the preview grid.

The preview also accepts a child <script type="layers/filter-groups"> with a filter group in the same format as the similar-products toggle.

Prices, currency, and Shopify Markets

The image-search and similar-products requests send context.market when window.Shopify.country contains a country code. The widget trims and uppercases the value, for example "ca" becomes "CA". If Shopify country is unavailable or empty, the widget omits context.market. The API then uses the request’s geo country, or the US if no country is available, and returns prices localized for that market. When the response includes _meta.pricing.currency_code, the widget uses it to format the returned prices. It resolves currency in this order:

currencyFormat.currency, if you explicitly configure it.
The response’s _meta.pricing.currency_code.
window.Shopify.currency.active.
USD.

The locale order is:

currencyFormat.locale, if you explicitly configure it.
window.Shopify.locale, with window.Shopify.country appended when the locale has no region subtag, such as en-CA.
The bare window.Shopify.locale.
en-US.

If the requested locale is invalid, the widget tries the bare Shopify locale and then en-US. Set explicit formatting when your storefront needs a fixed currency or locale:

window.Layers.widgetManager.configure({
  currencyFormat: {
    currency: 'EUR',
    locale: 'de-DE',
    style: 'currency',
    currencyDisplay: 'symbol'
  }
})

configure() merges currencyFormat properties, so setting only currency keeps the existing currency style and symbol display. For more about configuring Shopify market context, see Shopify Markets.

Styling

The widget applies theme values across its shadow roots. Set supported variables on :root in your theme CSS, or call window.Layers.widgetManager.updateTheme() to change them at runtime. The theme manager reads computed values from document.documentElement and observes changes to its style and class attributes.

:root {
  --layers-widget-color-primary: #234567;
  --layers-widget-font-family: Arial, sans-serif;
}

window.Layers.widgetManager.updateTheme({
  '--layers-widget-color-primary': '#234567',
  '--layers-widget-font-family': 'Arial, sans-serif'
})

The table lists every supported variable with its default. updateTheme() does not track --layers-widget-transition-properties; set that one in CSS.

Category	CSS variable	Default
Primary color	`--layers-widget-color-primary`	`#123fff`
Primary color	`--layers-widget-color-primary-hover`	`#607ffd`
Primary color	`--layers-widget-color-primary-light`	`rgba(18, 63, 255, 0.05)`
Primary color	`--layers-widget-color-primary-transparent`	`rgba(18, 63, 255, 0.2)`
UI color	`--layers-widget-color-text`	`#161616`
UI color	`--layers-widget-color-text-secondary`	`#707070`
UI color	`--layers-widget-color-text-light`	`#ffffff`
UI color	`--layers-widget-color-background`	`#ffffff`
UI color	`--layers-widget-color-border`	`#e5e5e5`
UI color	`--layers-widget-color-shadow`	`rgba(0, 0, 0, 0.1)`
UI color	`--layers-widget-color-hover-bg`	`rgba(0, 0, 0, 0.05)`
UI color	`--layers-widget-color-overlay-bg`	`rgba(0, 0, 0, 0.5)`
Product color	`--layers-widget-color-price`	`#161616`
Product color	`--layers-widget-color-compare-price`	`#9d9d9d`
Product color	`--layers-widget-product-image-bg`	`#f8f8f8`
Typography	`--layers-widget-font-family`	`-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif`
Typography	`--layers-widget-font-size-sm`	`0.9rem`
Typography	`--layers-widget-font-size-md`	`1rem`
Typography	`--layers-widget-font-size-lg`	`1.2rem`
Typography	`--layers-widget-font-size-xl`	`1.5rem`
Typography	`--layers-widget-font-weight-normal`	`400`
Typography	`--layers-widget-font-weight-medium`	`500`
Typography	`--layers-widget-font-weight-bold`	`600`
Spacing	`--layers-widget-spacing-xs`	`0.25rem`
Spacing	`--layers-widget-spacing-sm`	`0.5rem`
Spacing	`--layers-widget-spacing-md`	`0.75rem`
Spacing	`--layers-widget-spacing-lg`	`1rem`
Spacing	`--layers-widget-spacing-xl`	`1.25rem`
Spacing	`--layers-widget-spacing-xxl`	`1.5rem`
Spacing	`--layers-widget-spacing-xxxl`	`2.5rem`
Borders	`--layers-widget-border-radius-sm`	`0.25rem`
Borders	`--layers-widget-border-radius-md`	`0.5rem`
Borders	`--layers-widget-border-width`	`0.0625rem`
Borders	`--layers-widget-border-width-dashed`	`0.125rem`
Borders	`--layers-widget-border-style-dashed`	`dashed`
Icons	`--layers-widget-icon-size-sm`	`1rem`
Icons	`--layers-widget-icon-size-md`	`1.5rem`
Icons	`--layers-widget-icon-size-lg`	`2rem`
Icons	`--layers-widget-icon-size-xl`	`3rem`
Transitions	`--layers-widget-transition-duration`	`0.2s`
Transitions	`--layers-widget-transition-timing`	`ease`
Transitions	`--layers-widget-transition-properties`	`background-color, border-color, color, transform, box-shadow`
Dialog	`--layers-widget-dialog-max-width`	`28.125rem`
Dialog	`--layers-widget-dialog-width`	`28.125rem`
Dialog	`--layers-widget-dialog-max-height`	`100vh`
Dialog	`--layers-widget-dialog-shadow`	`-0.3125rem 0 1.25rem var(--layers-widget-color-shadow)`
Dialog	`--layers-widget-dialog-shadow-mobile`	`0 -0.3125rem 1.25rem var(--layers-widget-color-shadow)`
Dialog	`--layers-widget-dialog-border-radius`	`var(--layers-widget-border-radius-md)` (`0.5rem`)
Results	`--layers-widget-results-image-max-width`	`12.5rem`
Results	`--layers-widget-product-grid-columns`	`2`
Results	`--layers-widget-product-grid-columns-desktop`	`3`
Results	`--layers-widget-product-grid-columns-mobile`	`2`
Results	`--layers-widget-product-grid-columns-desktop-mobile`	`2`
Results	`--layers-widget-product-grid-gap`	`1rem`
Results	`--layers-widget-product-image-aspect-ratio`	`1 / 1`

Translations

You can change every piece of text the widgets show, including the modal heading, upload and crop steps, instructions, results, empty and error states, the clipboard and file messages, and the labels screen readers announce. Overrides are deep-merged over the built-in English text, so pass only the strings you want to change. Set copy for both widgets with configure():

<script>
  document.addEventListener('DOMContentLoaded', () => {
    window.Layers.widgetManager.configure({
      translations: {
        'image-search': {
          tooltip: { text: 'Try visual search' },
          modal: { header: { title: 'Search with a photo' } },
          steps: { upload: { button: { text: 'Upload a photo' } } },
          results: {
            states: {
              empty: { title: 'Nothing matched your photo' },
              error: { defaultText: 'We could not search right now. Please try again.' }
            }
          }
        },
        'similar-products': {
          results: { states: { error: { defaultText: 'Similar styles are unavailable right now.' } } }
        }
      }
    })
  })
</script>

updateTranslations(widgetType, translations) does the same for one widget at a time. Changes apply to open modals without a reload. To expose copy as theme settings, pass a JSON object on the image-search toggle with the translations attribute. Escape it so the JSON stays inside the attribute:

{%- capture image_search_copy -%}
  {"modal": {"header": {"title": {{ section.settings.visual_search_title | json }}}}}
{%- endcapture -%}

<layers-image-search-toggle
  icon="Camera"
  translations="{{ image_search_copy | escape }}"
></layers-image-search-toggle>

The main image-search groups are:

Group	What it covers
`tooltip`	Toggle tooltip text and its close button label.
`modal`	Modal heading, close button label, and Powered by footer.
`steps.upload`	Upload button, drag-and-drop area, paste button, privacy notice, and the instructions title, steps, and label.
`steps.choose`	Photo preview, Search with this photo, crop, and back buttons.
`steps.crop`	Crop instructions and the Back, Reset, and Select Area buttons.
`errors`	Messages for unsupported, empty, or denied clipboard access, a non-image file, and an image that fails to process.
`results`	Crop Image and New Search buttons, and the loading, success, empty, and error states.

The error state in both widgets always shows the configured results.states.error.defaultText. Shoppers never see the raw API error message.

Analytics

The widget exposes window.Layers.analytics.subscribe(handler) for its analytics events. When Clarity or Blotout is enabled, the app embed can also forward widget events to those services when their scripts are present and consent allows it. See app embed integrations.

Troubleshooting

Confirm that layout/theme.liquid includes the module script and that its src URL loads successfully.
Confirm that your page includes the appropriate custom element. The similar-products toggle and preview also need a product-id.
Check the browser console for script, configuration, or network errors.

The console says “No API key found”

Confirm that at least one token source is available: data-api-key on #layers-script, storefrontApiToken in the app embed’s #layers-config JSON, or window.Layers.widgetManager.setApiKey() / configure({ apiKey }). A token configured at initialization takes priority over later attribute changes.

Prices use the wrong currency

Check window.Shopify.country, window.Shopify.locale, and window.Shopify.currency.active on the storefront. Review the API response’s _meta.pricing.currency_code and any explicit currencyFormat settings, which take priority over Shopify’s active currency. See Shopify Markets.

Branding is still visible

Set data-hide-branding="true" on the script element with id="layers-script". If you set hideBranding with configure(), its boolean value overrides the script attribute.

Back does not reopen image search results

Confirm the page the shopper returns to includes <layers-image-search-toggle>. The toggle is what reopens the modal.
Check that the URL still contains layers_image_search after Back. Theme code that rewrites the URL with history.replaceState or pushState can drop the parameter.
Confirm the current tab has saved image-search state matching the URL image ID. If sessionStorage is unavailable, full, cleared, or mismatched, the widget removes the parameter and leaves the upload step active. The URL alone does not restore results.

Enable debug logging

Set data-debug="true" on #layers-script before the module initializes, or enable logging later:

window.Layers.widgetManager.configure({ debug: true })

Next steps

What the app embed handles for token delivery, storefront pixel behavior, and event forwarding.
Theme implementation checklist for the wider Shopify theme integration.
Shopify Markets for market and currency setup.
Liquid integration for reading Layers configuration and metaobjects in your theme.

Liquid Integration

Liquid + Fetch guides

Liquid + SDK guides

Visual Search widget

Overview

Prerequisites

Installation

Script attributes

API key resolution and load order

JavaScript configuration

Image search toggle

Restoring results after navigation

Custom upload content

Reference images and area-selection events

Similar-products toggle

Similar-products preview

Prices, currency, and Shopify Markets

Styling

Translations

Analytics

Troubleshooting

The widget does not appear

The console says “No API key found”

Prices use the wrong currency

Branding is still visible

Back does not reopen image search results

Enable debug logging

Next steps

​Overview

​Prerequisites

​Installation

​Script attributes

​API key resolution and load order

​JavaScript configuration

​Image search toggle

​Restoring results after navigation

​Custom upload content

​Reference images and area-selection events

​Similar-products toggle

​Similar-products preview

​Prices, currency, and Shopify Markets

​Styling

​Translations

​Analytics

​Troubleshooting

​The widget does not appear

​The console says “No API key found”

​Prices use the wrong currency

​Branding is still visible

​Back does not reopen image search results

​Enable debug logging

​Next steps

Overview

Prerequisites

Installation

Script attributes

API key resolution and load order

JavaScript configuration

Image search toggle

Restoring results after navigation

Custom upload content

Reference images and area-selection events

Similar-products toggle

Similar-products preview

Prices, currency, and Shopify Markets

Styling

Translations

Analytics

Troubleshooting

The widget does not appear

The console says “No API key found”

Prices use the wrong currency

Branding is still visible

Back does not reopen image search results

Enable debug logging

Next steps