Skip to main content

Web Components

Mimeeq provides powerful, framework-agnostic web components that allow you to easily integrate product visualization and authentication capabilities into any website or application, regardless of your tech stack.

Introduction to Web Components​

Web Components use native browser features to create encapsulated, reusable custom elements that work across modern browsers without requiring additional frameworks. This technology allows Mimeeq to deliver seamless integrations with:

  • Framework Independence: Works with React, Angular, Vue, or plain HTML
  • Encapsulation: Styles and behavior don't leak into or from your page
  • Reusability: Consistent behavior across multiple instances
  • Simplified Integration: Minimal code required to add complex functionality

Available Components​

Mimeeq provides two main web components:

1. <mmq-embed> Component​

The primary component for all product configuration experiences. It can render:

  • Standard product configurators (2D/3D)
  • Modular product configurators
  • Product lists with configurator capabilities
  • Favorites collections
  • And more based on the short code provided

2. <mmq-auth> Component​

Handles all authentication-related functionality:

  • Login forms
  • Password recovery
  • User profile management
  • Authentication state handling

Using the <mmq-embed> Component​

Basic Implementation​

<mmq-embed short-code="ABC123" template="template_id"></mmq-embed>
<script src="https://cdn.mimeeq.com/read_models/embed/app-embed.js" async></script>

Core Attributes​

The <mmq-embed> component has three primary attributes that you should focus on:

AttributeDescriptionTypeDefault
short-code(Required) The unique embed short code that identifies the product or list to displayString-
template(Required) ID of the embed template to applyString-
localeLanguage code for the configurator interfaceStringIt uses customer default language

Important: All other configuration options like visibility settings, colors, modal behaviors, etc. should be managed through embed templates in the Mimeeq Admin Panel rather than as component attributes. This approach provides better maintainability and consistency.

For information on creating and managing templates, see the Embed Templates documentation.

Methods​

The <mmq-embed> component provides several methods for programmatic control:

// Get a reference to your component
const configurator = document.querySelector('mmq-embed');

// Control visibility
await configurator.show();   // Display the configurator
await configurator.hide();   // Hide the configurator

For a complete list of available methods, please refer to the mmq-embed documentation.

Events​

The component emits various events that you can listen for in your application. Here are a few examples:

document.addEventListener('mimeeq-add-to-cart', (event) => {
  console.log('Product added to cart:', event.detail);
  // Add your own e-commerce integration code here
});

document.addEventListener('mimeeq-price-change', (event) => {
  console.log('Price updated:', event.detail.price);
  // Update external price displays
});

For a comprehensive list of all available events, please refer to the Events documentation.

Using the <mmq-auth> Component​

Basic Implementation​

<mmq-auth short-code="AUTH123" locale="en"></mmq-auth>
<script src="https://cdn.mimeeq.com/read_models/embed/app-embed.js" async></script>

Key Attributes​

AttributeDescriptionTypeDefault
short-code(Required) The unique authentication shortcode that identifies this authentication componentString-
localeThe locale code to use for translations and formatting (e.g., 'en', 'fr', 'de')String"en"
preserve-fontWhether to inherit the font family from your websiteBooleanundefined
accent-colorThe accent color for buttons and interactive elementsStringundefined
background-colorThe background color for authentication modalsStringundefined
accent-text-colorThe text color for text displayed on elements with accent color backgroundStringundefined

Methods​

The <mmq-auth> component provides methods for displaying various authentication interfaces:

// Get a reference to your auth component
const authComponent = document.querySelector('mmq-auth');

// Display login form in a modal dialog
await authComponent.mountLogin();

// Display user profile interface in a modal dialog
await authComponent.mountUserProfile();

// Display password recovery form in a modal dialog
await authComponent.mountForgotPassword();

Events​

// Wait for the auth component to load
document.addEventListener('mimeeq-auth-loaded', () => {
  console.log('Auth component loaded and ready to use');
  // Now it's safe to call methods on the component
});

// Listen for successful login
document.addEventListener('mimeeq-login-success', (event) => {
  console.log('User logged in:', event.detail);
  // Update UI to show logged-in state or refresh the page
  window.location.reload();
});

For a complete reference of all auth events, please see the Events documentation.

Understanding Shadow DOM​

Mimeeq web components utilize Shadow DOM for encapsulation, providing several important benefits:

Benefits​

  • Style Isolation: Component styles don't affect your page and vice versa
  • DOM Encapsulation: Component DOM structure is protected from external scripts
  • Simplified Styling: Clean integration without CSS conflicts
  • Performance: Better rendering performance through scope limitation

Working with Shadow DOM​

To access elements inside a component:

// INCORRECT - This won't work because of Shadow DOM encapsulation
document.querySelector('mmq-embed button.some-button');

// CORRECT - Access through the shadowRoot
const button = document.querySelector('mmq-embed')
  .shadowRoot.querySelector('button.some-button');

Styling Components​

There are two main approaches to styling components with Shadow DOM:

Mimeeq components expose CSS variables that allow styling without penetrating the Shadow DOM:

/* Your website CSS */
mmq-embed {
  --mmq-accent-color: #0066cc;
  --mmq-background-color: #f5f5f5;
  --mmq-text-color: #333333;
  --mmq-font-family: 'Roboto', sans-serif;
  --mmq-border-radius: 8px;
}

For a complete list of CSS variables, see the CSS Variables documentation.

2. CSS ::part() Selector​

For more specific styling, some component elements expose parts that can be targeted:

/* Style the option panel */
mmq-embed::part(option-panel) {
  border: 2px solid #cccccc;
  box-shadow: 0 4px 8px rgba(0,0,0,0.1);
}

/* Style buttons within the component */
mmq-embed::part(primary-button) {
  text-transform: uppercase;
  letter-spacing: 1px;
}

Integration Examples​

Basic Product Configurator​

<mmq-embed short-code="PROD123" template="standard_template"></mmq-embed>
<script src="https://cdn.mimeeq.com/read_models/embed/app-embed.js" async></script>

Product Configurator with E-commerce Integration​

<mmq-embed id="furniture-config" short-code="FURN789" template="ecommerce_template"></mmq-embed>

<script>
  document.addEventListener('mimeeq-add-to-cart', (event) => {
    // Extract product details from event
    const { productId, productName, image, price, quantity, selectedOptions } = event.detail;
    
    // Send to your e-commerce platform
    addToShoppingCart({
      id: productId,
      name: productName,
      image: image,
      price: price,
      quantity: quantity,
      options: selectedOptions
    });
    
    // Show confirmation to user
    showNotification(`Added ${productName} to your cart`);
  });
</script>
<script src="https://cdn.mimeeq.com/read_models/embed/app-embed.js" async></script>

Authentication Integration​

<mmq-auth short-code="AUTH123" locale="en"></mmq-auth>

<script>
  document.addEventListener('mimeeq-auth-loaded', () => {
    // Get a reference to the auth component
    const authComponent = document.querySelector('mmq-auth');
    
    // Display the login modal
    authComponent.mountLogin();
  });

  document.addEventListener('mimeeq-login-success', (event) => {
    // Update UI to show logged-in state
    document.querySelector('.login-button').style.display = 'none';
    document.querySelector('.user-menu').style.display = 'block';
    document.querySelector('.user-name').textContent = event.detail.firstName;
    
    // Fetch user-specific data
    loadUserFavorites();
  });
</script>
<script src="https://cdn.mimeeq.com/read_models/embed/app-embed.js" async></script>

Multiple Components on One Page​

<!-- User authentication -->
<mmq-auth short-code="AUTH123"></mmq-auth>

<!-- Product configurator -->
<mmq-embed short-code="PROD123" template="standard_template"></mmq-embed>

<!-- Load the script -->
<script src="https://cdn.mimeeq.com/read_models/embed/app-embed.js" async></script>
Important Limitation

While you can use multiple mmq-auth components on a page, you should generally avoid using multiple mmq-embed components simultaneously on the same page. The observers in the current implementation are not instance-bound, which means multiple embed components would interfere with each other and likely display the same products regardless of their individual settings.

Recommended approach: Instead of using multiple embed components, use a single mmq-embed component and dynamically change its short-code attribute when you need to display different products or configurations.

// Example: Switch between different products
const configurator = document.querySelector('mmq-embed');

// Show first product
configurator.setAttribute('short-code', 'PROD123');

// Later, switch to another product
configurator.setAttribute('short-code', 'PROD456');

Troubleshooting​

Common Issues​

Component not rendering:

  • Check that the script is loaded properly
  • Verify the short-code is correct
  • Template validation: Ensure your template ID exists and has no typos - if the template doesn't exist or has a typo, the component won't load anything at all
  • Double-check that both short-code and template attributes are spelled correctly (with hyphens)
  • Look for any JavaScript errors in your browser console

Style conflicts:

  • Remember that your page styles generally can't penetrate the Shadow DOM
  • Use CSS variables to customize component appearance
  • Check your CSS for any styles that might inadvertently affect component containers

Events not firing:

  • Add event listeners to the document, not to the component
  • Ensure event listeners are added before the component is initialized
  • Use event.detail to access event data

Browser Support​

Mimeeq web components support all modern browsers:

ChromeFirefoxEdgeSafariOpera
Latest ✅Latest ✅Latest ✅Latest ✅Latest ✅

Internet Explorer is not supported as it lacks native Web Components support.

Advanced Usage​

Lazy Loading Components​

For performance optimization, you can load components only when needed:

// Load the configurator only when it scrolls into view or a button is clicked
function loadConfigurator() {
  if (!window.configuratorLoaded) {
    const script = document.createElement('script');
    script.src = 'https://cdn.mimeeq.com/read_models/embed/app-embed.js';
    script.async = true;
    document.body.appendChild(script);
    window.configuratorLoaded = true;
  }
}

// Example: Load when a button is clicked
document.getElementById('configure-button').addEventListener('click', loadConfigurator);

// Example: Load when scrolled into view
const observer = new IntersectionObserver((entries) => {
  if (entries[0].isIntersecting) {
    loadConfigurator();
    observer.disconnect();
  }
});
observer.observe(document.querySelector('.configurator-container'));

Framework Integration​

While the components work natively with any framework, here are some tips for specific integrations:

React:

import { useEffect, useRef } from 'react';

function ProductConfigurator() {
  const configRef = useRef(null);
  
  useEffect(() => {
    // Load the script
    const script = document.createElement('script');
    script.src = 'https://cdn.mimeeq.com/read_models/embed/app-embed.js';
    script.async = true;
    document.body.appendChild(script);
    
    // Clean up
    return () => {
      document.body.removeChild(script);
    };
  }, []);
  
  return <mmq-embed ref={configRef} short-code="PROD123" template="standard_template"></mmq-embed>;
}

Vue:

<template>
  <mmq-embed 
    ref="configurator"
    short-code="PROD123" 
    template="standard_template">
  </mmq-embed>
</template>

<script>
export default {
  mounted() {
    if (!document.querySelector('script[src*="app-embed.js"]')) {
      const script = document.createElement('script');
      script.src = 'https://cdn.mimeeq.com/read_models/embed/app-embed.js';
      script.async = true;
      document.body.appendChild(script);
    }
    
    // Access component methods
    this.$refs.configurator.show();
  }
}
</script>

Angular:

import { Component, OnInit, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@Component({
  selector: 'app-product-configurator',
  template: `
    <mmq-embed 
      [attr.short-code]="shortCode" 
      [attr.template]="template">
    </mmq-embed>
  `
})
export class ProductConfiguratorComponent implements OnInit {
  shortCode = 'PROD123';
  template = 'standard_template';
  
  ngOnInit() {
    if (!document.querySelector('script[src*="app-embed.js"]')) {
      const script = document.createElement('script');
      script.src = 'https://cdn.mimeeq.com/read_models/embed/app-embed.js';
      script.async = true;
      document.body.appendChild(script);
    }
  }
}

// In your module
@NgModule({
  declarations: [ProductConfiguratorComponent],
  schemas: [CUSTOM_ELEMENTS_SCHEMA] // Required for web components
})

Further Resources​