GuideAPI Reference

Lens

Position this powerful lens component on top of any product image to enable similar product discovery. It adds a lens button to images that, when clicked, opens a dialog showing similar products.

Basic UsageCopied!

Add the <youzu-lens> tag inside a container with your product image:

<div style="position: relative;">
  <img 
    src="https://example.com/product-image.jpg" 
    alt="Product Image" 
    style="width: 100%; height: auto;"
  />
  <youzu-lens product-id="product-123"></youzu-lens>
</div>

Basic ExampleCopied!

HTMLCopied! 

<div style="position: relative; width: 500px; margin: 0 auto">
  <img
    src="https://images.unsplash.com/photo-1555041469-a586c61ea9bc"
    alt="Modern Sofa"
    style="width: 100%; height: auto; border-radius: 8px; box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1)"
  />
  <youzu-lens 
    product-id="modern-sofa-123" 
    button-position="bottom-right"
    button-size="48px"
    button-color="#0066cc"
    button-icon-color="#ffffff"
    button-opacity="0.8"
    button-hover-opacity="1.0"
    caption-text="Find similar furniture"
    show-caption="true"
    dialog-title="Similar Furniture"
    result-limit="8"
    category-filter="furniture">
  </youzu-lens>
</div>

JavaScriptCopied! 

document.addEventListener('DOMContentLoaded', () => {
  const youzuLens = document.querySelector('youzu-lens');
  
  // Listen for dialog open
  youzuLens.addEventListener('dialogOpen', event => {
    console.log('Dialog opened for product:', event.detail.productId);
  });
  
  // Listen for product selection
  youzuLens.addEventListener('productSelected', event => {
    const { productId, productName, price } = event.detail;
    console.log(`Product selected: ${productName} (${productId}) - ${price}`);
    
    // Show alert
    alert(`Product selected: ${productName} - ${price}`);
  });
  
  // Listen for products added to basket
  youzuLens.addEventListener('productAddedToBasket', event => {
    const { productId, productName, price, quantity } = event.detail;
    console.log(`Product added to basket: ${productName} - ${price} x ${quantity}`);
    
    // Show alert
    alert(`Added to basket: ${productName} - ${price}`);
  });
  
  // Open dialog programmatically
  document.getElementById('open-lens-dialog').addEventListener('click', () => {
    youzuLens.openDialog();
  });
});

DemoCopied!

PropsCopied!

Prop Type Default Description
product-id String Required Unique identifier for the product.
button-position String "bottom-right" Position of the lens button. Options: "top-left", "top-right", "bottom-left", "bottom-right".
button-size String "40px" Size of the lens button.
button-color String "#000000" Background color of the lens button.
button-icon-color String "#ffffff" Color of the lens icon.
button-opacity Number 0.7 Opacity of the lens button.
button-hover-opacity Number 1.0 Opacity of the lens button on hover.
button-offset String "10px" Offset of the button from the edge.
caption-text String "Find similar" Text displayed as caption/tooltip.
show-caption Boolean false Whether to display the caption.
dialog-title String "Similar Products" Title of the similar products dialog.
target-selector String "" CSS selector of the target image. If not set, uses the previous sibling image.
product-data Object null Product data to use for similarity search.
auto-detect-product Boolean true Whether to automatically detect the product in the image.
result-limit Number 12 Maximum number of similar products to display.
category-filter String "" Filter results by product category.
price-range String "" Filter results by price range (e.g., "10-50").

EventsCopied!

The YouZu Lens component emits the following events:

Event Detail Description
dialogOpen { productId } Fired when the similar products dialog is opened.
dialogClose { productId } Fired when the similar products dialog is closed.
productSelected { productId, productName, price, imageUrl } Fired when a product is selected from the dialog.
productAddedToBasket { productId, productName, price, quantity } Fired when a product is added to the basket.
searchStarted { productId } Fired when a similarity search starts.
searchComplete { productId, resultCount } Fired when a similarity search completes.
searchError { productId, error } Fired when a similarity search fails.

MethodsCopied!

The YouZu Lens component exposes the following methods:

Method Parameters Return Description
openDialog() None Promise Opens the similar products dialog.
closeDialog() None Promise Closes the similar products dialog.
setSimilarProducts(products) products: Array Promise Sets the similar products displayed in the dialog.
getProductData() None Promise Gets the current product data.
refresh() None Promise Refreshes the similar products.

Advanced UsageCopied!

Custom Product DataCopied!

You can provide custom product data to enhance the similarity search:

const youzuLens = document.querySelector('youzu-lens');

// Set custom product data
youzuLens.product-data = {
  id: 'custom-sofa-123',
  name: 'Modern Sectional Sofa',
  price: '$899',
  currency: 'USD',
  category: 'furniture',
  subcategory: 'sofas',
  description: 'A comfortable modern sectional sofa with chaise lounge',
  color: 'gray',
  material: 'fabric',
  dimensions: {
    width: '94 inches',
    depth: '64 inches',
    height: '36 inches'
  },
  imageUrl: 'https://example.com/sofa.jpg',
  productUrl: 'https://example.com/products/modern-sectional-sofa'
};

Custom Similar Products DisplayCopied!

You can customize how similar products are displayed:

const youzuLens = document.querySelector('youzu-lens');

// Set custom similar products
youzuLens.setSimilarProducts([
  {
    id: 'product-1',
    name: 'Gray Fabric Sofa',
    price: '$799',
    imageUrl: 'https://example.com/sofa1.jpg',
    productUrl: 'https://example.com/products/gray-fabric-sofa'
  },
  {
    id: 'product-2',
    name: 'Modern Sectional',
    price: '$1,099',
    imageUrl: 'https://example.com/sofa2.jpg',
    productUrl: 'https://example.com/products/modern-sectional'
  }
  // Add more products as needed
]);

Dynamically Creating YouZu Lens ComponentsCopied!

You can dynamically create and attach YouZu Lens components to product images:

function attachLensToProducts() {
  // Find all product images
  const productImages = document.querySelectorAll('.product-image');
  
  productImages.forEach(image => {
    // Get product ID from data attribute
    const productId = image.dataset.productId;
    
    // Create a container for positioning
    const container = document.createElement('div');
    container.style.position = 'relative';
    container.style.display = 'inline-block';
    
    // Replace the image with the container and move the image inside
    image.parentNode.insertBefore(container, image);
    container.appendChild(image);
    
    // Create and add the YouZu Lens component
    const lens = document.createElement('youzu-lens');
    lens.setAttribute('product-id', productId);
    lens.setAttribute('button-position', 'bottom-right');
    container.appendChild(lens);
  });
}

// Call the function when the page loads
document.addEventListener('DOMContentLoaded', attachLensToProducts);

StylingCopied!

The YouZu Lens component can be customized using CSS variables:

<youzu-lens 
  style="--youzu-button-color: #ff5722; --youzu-button-icon-color: #ffffff; --youzu-button-size: 50px;">
</youzu-lens>

Available CSS variables:

--youzu-button-color: #000000;
--youzu-button-icon-color: #ffffff;
--youzu-button-size: 40px;
--youzu-button-opacity: 0.7;
--youzu-button-hover-opacity: 1.0;
--youzu-button-offset: 10px;
--youzu-dialog-background: #ffffff;
--youzu-dialog-text-color: #333333;
--youzu-dialog-accent-color: #0066cc;

For additional help, contact our support team.