Implement image-based product search and similar product discovery on your Shopify storefront with our easy-to-use 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.
Layers provides two main visual search widgets:
Allows customers to search for products by uploading an image or selecting part of an image on your site.
Shows customers products visually similar to the one they’re currently viewing.
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.
Your Layers API key, which can be found in your Layers dashboard.
Enable debug mode for console logging. Useful for troubleshooting during development.
After the script is loaded, you can configure the widget manager with global options:
Your Layers API key.
Enable debug mode for console logging.
The Image Search Widget allows customers to search for products using an image they upload or select.
Container element or selector where the toggle button will be placed.
ID of a template element for custom content in the upload step. This can include sample images and helpful tips.
Upload mode: drag-drop
(shows a drag-and-drop area) or button
(shows a button for uploading, better for mobile).
Icon to use: ScanSearch
, Search
, or Camera
.
Additional CSS class names for styling.
A facet code to enable filtering in the results modal.
Configuration for the tooltip feature (see below).
The tooltip
option accepts an object with the following properties:
Whether to show the tooltip.
Text to display in the tooltip.
Time in milliseconds before tooltip auto-closes.
Maximum number of times to show tooltip to user.
Whether to show an X button to dismiss tooltip.
You can provide a custom template for the upload step that includes sample images and helpful tips:
You can create clickable images that open the image search:
Listen for area selection events to perform custom actions:
The Shop Similar Widget allows customers to view products similar to a specific product.
Container element or selector where the toggle button will be placed.
ID of the product to find similar items for.
Icon to use (currently only supports Sparkles
).
A facet code to enable filtering in the results modal.
Additional CSS class names for styling.
You can specify advanced filtering using a script tag with type “layers/filter-groups” inside the toggle element:
The Similar Products Preview Widget displays a grid of similar products directly on your product page and opens the Similar Products modal when clicked.
Container element or selector where the preview widget will be placed.
ID of the product to find similar items for.
Number of similar products to display in the preview grid.
Whether to defer loading similar products until the widget is scrolled into view.
A facet code to enable filtering in the results modal.
Additional CSS class names for styling.
You can specify advanced filtering using a script tag with type “layers/filter-groups” inside the preview element, just like with the toggle widget:
Customize the look and feel of the widgets using CSS custom properties. You can set these in your CSS or update them dynamically:
For a complete list of theme properties, check out our theme customization reference.
Customize the text used in widgets:
The widgets emit analytics events that you can subscribe to for integration with your analytics platforms:
Event Type | Description |
---|---|
similar-opened | Shop Similar modal was opened |
similar-closed | Shop Similar modal was closed |
similar-product-clicked | A product in the Shop Similar results was clicked |
image-search-opened | Image Search modal was opened |
image-search-closed | Image Search modal was closed |
image-search-search | Image Search was performed |
image-search-crop | Image was cropped in Image Search |
image-search-image-uploaded | Image was uploaded in Image Search |
Colors - Primary
Property | Default | Description |
---|---|---|
--layers-widget-color-primary | #ff4500 | Primary color for buttons and accents |
--layers-widget-color-primary-hover | #ff6347 | Hover state for primary color elements |
--layers-widget-color-primary-light | rgba(255, 69, 0, 0.05) | Light version of primary color for backgrounds |
--layers-widget-color-primary-transparent | rgba(255, 69, 0, 0.2) | Transparent version of primary color |
Colors - UI
Property | Default | Description |
---|---|---|
--layers-widget-color-text | #333333 | Main text color |
--layers-widget-color-text-secondary | #666666 | Secondary text color |
--layers-widget-color-text-light | #ffffff | Light text color (for dark backgrounds) |
--layers-widget-color-background | #ffffff | Background color |
--layers-widget-color-border | #e0e0e0 | Border color |
--layers-widget-color-shadow | rgba(0, 0, 0, 0.1) | Shadow color |
--layers-widget-color-hover-bg | rgba(0, 0, 0, 0.05) | Background color for hover states |
--layers-widget-color-overlay-bg | rgba(0, 0, 0, 0.5) | Background color for overlays |
Typography
Property | Default | Description |
---|---|---|
--layers-widget-font-family | -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif | Font family for all text in the widgets |
--layers-widget-font-size-sm | 0.9rem | Small font size |
--layers-widget-font-size-md | 1rem | Medium font size (base) |
--layers-widget-font-size-lg | 1.2rem | Large font size |
--layers-widget-font-size-xl | 1.5rem | Extra large font size |
--layers-widget-font-weight-normal | 400 | Normal font weight |
--layers-widget-font-weight-medium | 500 | Medium font weight |
--layers-widget-font-weight-bold | 600 | Bold font weight |
Spacing
Property | Default | Description |
---|---|---|
--layers-widget-spacing-xs | 0.25rem | Extra small spacing |
--layers-widget-spacing-sm | 0.5rem | Small spacing |
--layers-widget-spacing-md | 0.75rem | Medium spacing |
--layers-widget-spacing-lg | 1rem | Large spacing |
--layers-widget-spacing-xl | 1.25rem | Extra large spacing |
--layers-widget-spacing-xxl | 1.5rem | Double extra large spacing |
--layers-widget-spacing-xxxl | 2.5rem | Triple extra large spacing |
Borders and Shadows
Property | Default | Description |
---|---|---|
--layers-widget-border-radius-sm | 0.25rem | Small border radius |
--layers-widget-border-radius-md | 0.5rem | Medium border radius |
--layers-widget-border-width | 0.0625rem | Border width |
--layers-widget-border-width-dashed | 0.125rem | Dashed border width |
--layers-widget-border-style-dashed | dashed | Dashed border style |
Icons and Transitions
Property | Default | Description |
---|---|---|
--layers-widget-icon-size-sm | 1rem | Small icon size |
--layers-widget-icon-size-md | 1.5rem | Medium icon size |
--layers-widget-icon-size-lg | 2rem | Large icon size |
--layers-widget-icon-size-xl | 3rem | Extra large icon size |
--layers-widget-transition-duration | 0.2s | Transition duration |
--layers-widget-transition-timing | ease | Transition timing function |
Dialog and Layout
Property | Default | Description |
---|---|---|
--layers-widget-dialog-max-width | 28.125rem | Maximum width of dialog |
--layers-widget-dialog-width | 28.125rem | Width of dialog |
--layers-widget-dialog-max-height | 100vh | Maximum height of dialog |
--layers-widget-dialog-shadow | -0.3125rem 0 1.25rem rgba(0, 0, 0, 0.1) | Shadow for dialog |
--layers-widget-dialog-shadow-mobile | 0 -0.3125rem 1.25rem rgba(0, 0, 0, 0.1) | Shadow for dialog on mobile |
--layers-widget-dialog-border-radius | 0.5rem | Border radius for dialog |
Product Display
Property | Default | Description |
---|---|---|
--layers-widget-results-image-max-width | 12.5rem | Maximum width of product images in results |
--layers-widget-product-grid-columns | 2 | Number of columns in product grid |
--layers-widget-product-grid-columns-desktop | 3 | Number of columns in product grid on desktop |
--layers-widget-product-grid-columns-mobile | 1 | Number of columns in product grid on mobile |
--layers-widget-product-grid-columns-desktop-mobile | 2 | Number of columns in product grid on tablet |
--layers-widget-product-grid-gap | 1rem | Gap between products in grid |
--layers-widget-product-image-aspect-ratio | 1 / 1 | Aspect ratio for product images |
--layers-widget-product-image-bg | #f8f8f8 | Background color for product images |
--layers-widget-color-price | #333333 | Color for product prices |
--layers-widget-color-compare-price | #999999 | Color for compare-at prices |
If the widget doesn’t appear:
Enable debug mode to see detailed logs in the console:
For more detailed troubleshooting, please contact Layers support.