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.

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.

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 and analytics

Use updateTranslations() to deep-merge custom text for either widget:

window.Layers.widgetManager.updateTranslations('image-search', {
  modal: {
    header: {
      title: 'Find products with an image'
    }
  }
})

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.

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

Custom upload content

Reference images and area-selection events

Similar-products toggle

Similar-products preview

Prices, currency, and Shopify Markets

Styling

Translations and analytics

Troubleshooting

The widget does not appear

The console says “No API key found”

Prices use the wrong currency

Branding is still visible

Enable debug logging

Next steps

​Overview

​Prerequisites

​Installation

​Script attributes

​API key resolution and load order

​JavaScript configuration

​Image search toggle

​Custom upload content

​Reference images and area-selection events

​Similar-products toggle

​Similar-products preview

​Prices, currency, and Shopify Markets

​Styling

​Translations and analytics

​Troubleshooting

​The widget does not appear

​The console says “No API key found”

​Prices use the wrong currency

​Branding is still visible

​Enable debug logging

​Next steps

Overview

Prerequisites

Installation

Script attributes

API key resolution and load order

JavaScript configuration

Image search toggle

Custom upload content

Reference images and area-selection events

Similar-products toggle

Similar-products preview

Prices, currency, and Shopify Markets

Styling

Translations and analytics

Troubleshooting

The widget does not appear

The console says “No API key found”

Prices use the wrong currency

Branding is still visible

Enable debug logging

Next steps