Our visual search widgets provide an easy way to implement advanced AI-powered image search and similar product discovery on your Shopify storefront. The widgets are designed to be lightweight, customizable, and simple to integrate.

​
Widget Overview

Layers provides two main visual search widgets:

Image Search

Allows customers to search for products by uploading an image or selecting part of an image on your site.

Shop Similar

Shows customers products visually similar to the one they’re currently viewing.

​
Installation

Add the Layers Widgets to your site by including a single script tag in your theme’s theme.liquid file, just before the closing </body> tag.

<script 
  src="https://cdn.uselayers.com/widget/layers-widget.js" 
  data-api-key="YOUR_LAYERS_API_KEY" 
  module
></script>

​
Script Attributes

​
data-api-key
string
required

Your Layers API key, which can be found in your Layers dashboard.

​
data-debug
boolean
default:"false"

Enable debug mode for console logging. Useful for troubleshooting during development.

​
Global Configuration

After the script is loaded, you can configure the widget manager with global options:

window.Layers.widgetManager.configure({
  apiKey: 'YOUR_LAYERS_API_KEY',
  debug: false
});

​
Configuration Options

​
apiKey
string
required

Your Layers API key.

​
debug
boolean
default:"false"

Enable debug mode for console logging.

​
Image Search Widget

The Image Search widget allows customers to search for products using an image they upload or select.

​
Basic Implementation

// Create an image search toggle button
window.Layers.widgetManager.createImageSearchToggle({
  container: '#image-search-container',
  uploadMode: 'drag-drop',
  icon: 'ScanSearch',
  className: 'my-custom-class'
});

​
Configuration Options

​
container
string | HTMLElement
required

Container element or selector where the toggle button will be placed.

​
templateId
string

ID of a template element for custom content in the upload step. This can include sample images and helpful tips.

​
uploadMode
string
default:"drag-drop"

Upload mode: drag-drop (shows a drag-and-drop area) or button (shows a button for uploading, better for mobile).

​
icon
string
default:"ScanSearch"

Icon to use: ScanSearch, Search, or Camera.

​
className
string

Additional CSS class names for styling.

​
Custom Template

You can provide a custom template for the upload step that includes sample images and helpful tips:

<template id="custom-image-search-template">
  <div class="custom-content">
    <p>Take a photo or upload an image to find similar products.</p>
    <div class="sample-images">
      <img src="/sample1.jpg" alt="Sample 1" />
      <img src="/sample2.jpg" alt="Sample 2" />
    </div>
  </div>
</template>

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

​
Reference Images

You can create clickable images that open the image search:

<layers-image-search-reference-image src="/path/to/image.jpg">
  <img src="/path/to/image.jpg" alt="Click to search for similar items" />
</layers-image-search-reference-image>

​
Event Handling

Listen for area selection events to perform custom actions:

document.querySelector('layers-image-search-toggle')
  .addEventListener('layers-image-search-area-selected', (event) => {
    const selectedArea = event.detail;
    console.log('Area selected:', selectedArea);
    // Perform custom actions with the selected area
  });

​
Shop Similar Widget

The Shop Similar widget allows customers to view products similar to a specific product.

​
Basic Implementation

// Create a similar products toggle button
window.Layers.widgetManager.createSimilarProductsToggle({
  container: '#similar-products-container',
  productId: '1234567890',
  icon: 'Sparkles',
  className: 'my-custom-class'
});

​
Configuration Options

​
container
string | HTMLElement
required

Container element or selector where the toggle button will be placed.

​
productId
string
required

ID of the product to find similar items for.

​
icon
string
default:"Sparkles"

Icon to use (currently only supports Sparkles).

​
className
string

Additional CSS class names for styling.

​
Advanced Filtering with Filter Groups

You can specify advanced filtering using a script tag with type “layers/filter-groups” inside the toggle element:

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

​
Customization

​
Theme Customization

Customize the look and feel of the widgets using CSS custom properties. You can set these in your CSS or update them dynamically:

// Update theme properties
window.Layers.widgetManager.updateTheme({
  '--layers-widget-color-primary': '#ff4500',
  '--layers-widget-color-text': '#333333',
  '--layers-widget-font-family': 'Helvetica, Arial, sans-serif'
});

For a complete list of theme properties, check out our theme customization reference.

​
Translation Customization

Customize the text used in widgets:

// Update translations for the image search widget
window.Layers.widgetManager.updateTranslations('image-search', {
  modal: {
    header: {
      title: 'Find Products Using an Image'
    }
  },
  steps: {
    upload: {
      title: 'Upload a Photo'
    }
  }
});

​
Analytics Integration

The widgets emit analytics events that you can subscribe to for integration with your analytics platforms:

// Subscribe to analytics events
window.Layers.analytics.subscribe((eventType, data) => {
  console.log(`Event: ${eventType}`, data);
  
  // Example integration with Google Analytics 4
  if (typeof gtag === 'function') {
    gtag('event', eventType, {
      ...data,
      event_category: 'Layers Visual Search'
    });
  }
});

​
Event Types

Event TypeDescription
similar-openedShop Similar modal was opened
similar-closedShop Similar modal was closed
similar-product-clickedA product in the Shop Similar results was clicked
image-search-openedImage Search modal was opened
image-search-closedImage Search modal was closed
image-search-searchImage Search was performed
image-search-cropImage was cropped in Image Search

​
Theme Customization Reference

​
Troubleshooting

​
Widget Not Appearing

If the widget doesn’t appear:

  1. Check that the script is loaded properly
  2. Verify your API key is valid
  3. Look for JavaScript errors in the console
  4. Ensure the container element exists

​
Enable Debug Mode

Enable debug mode to see detailed logs in the console:

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

For more detailed troubleshooting, please contact Layers support.