Magic Background

Enhance your product images automatically with this Magic Background component by adding appropriate contextual backgrounds. This is particularly useful for product images with white or transparent backgrounds, allowing them to be displayed in more attractive and context-appropriate settings.

Basic UsageCopied!

Add the <youzu-magic-background> tag in place of a standard <img> element:

<youzu-magic-background
  src="https://example.com/product.jpg"
  alt="Product Image"
  mode="auto"
  style-preset="modern"
  width="100%">
</youzu-magic-background>

Basic ExamplesCopied!

<div style="display: flex; flex-wrap: wrap; gap: 30px; margin-top: 20px">
  <!-- Auto Mode Example -->
  <div style="flex: 1; min-width: 300px">
    <h4>Auto Mode</h4>
    <p>Automatically detects if a background is needed</p>
    <youzu-magic-background
      src="https://example.com/chair-product.jpg"
      alt="Chair product"
      mode="auto"
      style-preset="modern"
      width="100%">
    </youzu-magic-background>
  </div>

  <!-- Always Mode Example -->
  <div style="flex: 1; min-width: 300px">
    <h4>Always Mode (with hideLoading)</h4>
    <p>Always applies a background with loading indicator hidden</p>
    <youzu-magic-background
      src="https://example.com/chair-product.jpg"
      alt="Chair product"
      mode="always"
      style-preset="minimalist"
      hide-loading
      width="100%">
    </youzu-magic-background>
  </div>
</div>

<!-- Manual Mode Example with Controls -->
<div style="margin-top: 30px">
  <h4>Manual Mode</h4>
  <p>Apply backgrounds on demand with different styles</p>

  <div style="margin-bottom: 15px">
    <select id="bgStyleSelect" style="padding: 8px; border-radius: 4px; border: 1px solid #ddd">
      <option value="modern">Modern Style</option>
      <option value="minimalist">Minimalist Style</option>
      <option value="classic">Classic Style</option>
      <option value="luxury">Luxury Style</option>
    </select>
    <button id="applyBgBtn" style="margin-left: 10px; padding: 8px 16px; background-color: #4caf50; color: white; border: none; border-radius: 4px; cursor: pointer">
      Apply Background
    </button>
  </div>

  <youzu-magic-background
    id="manualBackgroundDemo"
    src="https://example.com/chair-product.jpg"
    alt="Chair product"
    mode="manual"
    width="100%">
  </youzu-magic-background>
</div>

<script>
  document.addEventListener('DOMContentLoaded', () => {
    // Manual mode controls
    const manualBackground = document.getElementById('manualBackgroundDemo');
    const bgStyleSelect = document.getElementById('bgStyleSelect');
    const applyBgBtn = document.getElementById('applyBgBtn');
    
    // Listen for background change events
    const magicBackgrounds = document.querySelectorAll('youzu-magic-background');
    magicBackgrounds.forEach(background => {
      background.addEventListener('backgroundChange', event => {
        console.log('Background change:', event.detail);
      });
    });
    
    applyBgBtn.addEventListener('click', async () => {
      const selectedStyle = bgStyleSelect.value;
      try {
        applyBgBtn.textContent = 'Applying...';
        applyBgBtn.disabled = true;
        
        await manualBackground.applyBackground({ stylePreset: selectedStyle });
        console.log('Background applied with style:', selectedStyle);
      } catch (error) {
        console.error('Error applying background:', error);
      } finally {
        applyBgBtn.textContent = 'Apply Background';
        applyBgBtn.disabled = false;
      }
    });
  });
</script>

DemoCopied!

PropsCopied!

Prop	Type	Default	Description
`src`	String	Required	URL of the product image.
`alt`	String	`""`	Alternative text for the image.
`mode`	String	`"auto"`	Background generation mode. Options: `"auto"`, `"always"`, `"manual"`.
`style-preset`	String	`"modern"`	Visual style preset for the background. Options: `"modern"`, `"minimalist"`, `"classic"`, `"luxury"`.
`width`	String	`"auto"`	Width of the component.
`height`	String	`"auto"`	Height of the component.
`hide-loading`	Boolean	`false`	Whether to hide the loading indicator.
`fallback-behavior`	String	`"original"`	Behavior when background generation fails. Options: `"original"`, `"placeholder"`, `"none"`.
`product-type`	String	`""`	Type of product to optimize background generation. E.g., `"furniture"`, `"fashion"`, `"electronics"`.
`color-theme`	String	`""`	Color theme for the background. E.g., `"warm"`, `"cool"`, `"neutral"`.
`environment`	String	`""`	Environment for context. E.g., `"living-room"`, `"outdoor"`, `"studio"`.
`quality`	String	`"high"`	Image quality. Options: `"low"`, `"medium"`, `"high"`.
`animation`	String	`"fade"`	Animation type for transition. Options: `"none"`, `"fade"`, `"zoom"`.
`animation-duration`	Number	`500`	Duration of the animation in milliseconds.

EventsCopied!

The YouZu Magic Background component emits the following events:

Event	Detail	Description
`load`	`{ originalSrc }`	Fired when the original image is loaded.
`backgroundStart`	`{ originalSrc }`	Fired when background generation starts.
`backgroundChange`	`{ originalSrc, backgroundSrc, stylePreset }`	Fired when the background is changed.
`backgroundError`	`{ originalSrc, error }`	Fired when background generation fails.

MethodsCopied!

The YouZu Magic Background component exposes the following methods:

Method	Parameters	Return	Description
`applyBackground(options)`	`options`: Object	Promise	Applies a background to the image with the specified options.
`resetToOriginal()`	None	Promise	Resets to the original image without a background.
`preloadBackground(options)`	`options`: Object	Promise	Preloads a background without applying it.
`getBackgroundUrl()`	None	Promise	Gets the URL of the current background image.

Advanced UsageCopied!

Custom Background OptionsCopied!

The applyBackground method accepts several options to customize the generated background:

const magicBackground = document.querySelector('youzu-magic-background');

async function applyCustomBackground() {
  try {
    await magicBackground.applyBackground({
      stylePreset: 'luxury',
      colorTheme: 'warm',
      environment: 'living-room',
      shadow: true,
      reflection: true,
      depth: 'medium',
      lighting: 'soft',
      perspective: 'front',
      format: 'jpg',
      quality: 90
    });
  } catch (error) {
    console.error('Failed to apply background:', error);
  }
}

A/B Testing Different BackgroundsCopied!

const magicBackground = document.querySelector('youzu-magic-background');
const styles = ['modern', 'minimalist', 'classic', 'luxury'];
let currentStyleIndex = 0;

function rotateBackgroundStyles() {
  currentStyleIndex = (currentStyleIndex + 1) % styles.length;
  const style = styles[currentStyleIndex];
  
  magicBackground.applyBackground({ stylePreset: style });
  document.getElementById('current-style').textContent = style;
}

// Rotate styles every 3 seconds
setInterval(rotateBackgroundStyles, 3000);

Performance ConsiderationsCopied!

Use hide-loading for a smoother user experience when you know a background will be applied
Set appropriate width and height attributes to prevent layout shifts
Use quality: "medium" for faster loading on mobile devices
Consider using preloadBackground() to prepare backgrounds before they're needed

For additional help, contact our support team.