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’stheme.liquid
file, just before the closing </body>
tag.
Script Attributes
Your Layers API key, which can be found in your Layers dashboard.
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:Configuration Options
Your Layers API key.
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
Configuration Options
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).
Tooltip Configuration
Thetooltip
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.
Custom Template
You can provide a custom template for the upload step that includes sample images and helpful tips:Reference Images
You can create clickable images that open the image search:Event Handling
Listen for area selection events to perform custom actions:Shop Similar Widget
The Shop Similar Widget allows customers to view products similar to a specific product.Basic Implementation
Configuration Options
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.
Advanced Filtering with Filter Groups
You can specify advanced filtering using a script tag with type “layers/filter-groups” inside the toggle element: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.Configuration Options
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.
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: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:Translation Customization
Customize the text used in widgets:Analytics Integration
The widgets emit analytics events that you can subscribe to for integration with your analytics platforms:Event Types
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 |
Theme Customization Reference
Colors - Primary
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
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
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
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
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
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
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
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 |
Troubleshooting
Widget Not Appearing
If the widget doesn’t appear:- Check that the script is loaded properly
- Verify your API key is valid
- Look for JavaScript errors in the console
- Ensure the container element exists