Visual Search Widgets

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:

​

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

​

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
});

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

<!-- Configuration is handled through the script tag attributes -->
<script 
  src="https://cdn.uselayers.com/widget/layers-widget.js" 
  data-api-key="YOUR_LAYERS_API_KEY" 
  data-debug="false"
  async
></script>

​

Configuration Options

​

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',
  tooltip: {
    enabled: true,
    text: 'NEW: Search with your camera',
    duration: 5000,
    maxShows: 3,
    showCloseButton: true
  }
});

// Create an image search toggle button
window.Layers.widgetManager.createImageSearchToggle({
  container: '#image-search-container',
  uploadMode: 'drag-drop',
  icon: 'ScanSearch',
  className: 'my-custom-class',
  tooltip: {
    enabled: true,
    text: 'NEW: Search with your camera',
    duration: 5000,
    maxShows: 3,
    showCloseButton: true
  }
});

<!-- Add a button that opens the image search modal -->
<layers-image-search-toggle 
  upload-mode="drag-drop" 
  icon="CameraSearch"
  class="my-custom-class"
  tooltip-text="NEW: Search with your camera"
  tooltip-duration="5000"
  tooltip-max-shows="3"
  tooltip-show-close-button="true"
  tooltip-enabled="true">
</layers-image-search-toggle>

​

Configuration Options

​

Tooltip Configuration

The tooltip option accepts an object with the following properties:

​

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'
});

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

<!-- Add a button that opens the similar products modal -->
<layers-similar-products-toggle 
  product-id="1234567890" 
  icon="Sparkles"
  class="my-custom-class">
</layers-similar-products-toggle>

​

Configuration Options

​

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>

​

Similar Products Preview Widget

The Similar Products Preview Widget displays a grid of similar products directly on your product page and opens the Similar Products modal when clicked.

// Create a similar products preview grid
window.Layers.widgetManager.createSimilarProductsPreview({
  container: '#similar-products-preview-container',
  productId: '1234567890',
  limit: 4,
  lazyLoad: true
});

// Create a similar products preview grid
window.Layers.widgetManager.createSimilarProductsPreview({
  container: '#similar-products-preview-container',
  productId: '1234567890',
  limit: 4,
  lazyLoad: true
});

<!-- Add a grid that displays similar products previews -->
<layers-similar-products-preview 
  product-id="1234567890" 
  limit="4"
  lazy-load="true">
</layers-similar-products-preview>

​

Configuration Options

​

Advanced Filtering with Filter Groups

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

<layers-similar-products-preview product-id="1234567890" limit="4">
  <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-preview>

​

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

​

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.