Use variant switching and media

Displaying Product Variants

In Composable Commerce, each Product Projection includes a Master Variant along with an array of the other variants. The Master Variant is the default version of the Product and is typically displayed at the default selected variant on the product detail page and other pages, such as the product listing page (PLP). Additional variants represent alternate configurations—such as different sizes, colors, or styles—that the Customer can select.

When rendering the product and its variant options, a key consideration is how to handle stock availability. You need to decide whether customers should be able to select and add variants to their cart even if they are out of stock for the relevant inventory supply channels associated with your website or app (for example, allowing backorders or pre-orders). If unavailable variants should not be selectable, then you may use the availability object, which will tell you what inventory is present for each Variant per Channel.

Code context and API response

Before building variant switching logic, retrieve a Product via the endpoint we've previously discussed. In the response, inspect the following:

• The masterVariant – which holds the primary display version of the Product.
• The variants[] array – which contains other Variants.

• Master Variant (Default)
  • id: f955d965-11be-4bf5-a552-5328852c9d3a
  • sku: "CSKW-093"
  • key: "cottonSilkBedsheet01"
  • prices: AUD and NZD
  • attributes: Size = Queen, Color = White
  • images: Main display image
• Additional variants (variants[] in the response)
• 8 additional variants with unique sku, attributes, prices, and images.
• Attributes might differ (for example, Size = Twin, King), allowing user-driven selection.

Best practices for variant switching

A well-designed variant switching interface allows users to explore different configurations of a product—such as size, color, or material—without navigating away or reloading the page. Below are the recommended best practices to help you build a seamless variant selection experience:

Example logic

The following is a pseudocode snippet to illustrate the logic:

// Assume the 'product' object is the API response containing masterVariant and variants

let selectedVariant = product.masterVariant; // Display the master variant by default

// Function to render the product details based on the selected variant
function renderProductDetails(variant) {
  // Update the UI components with variant.price, variant.images, variant.attributes, etc.
  console.log('Displaying variant:', variant);
}

// Example UI: Creating buttons for each variant
product.variants.forEach((variant) => {
  const button = document.createElement('button');
  // For instance, display size attribute as the button text
  const sizeAttribute = variant.attributes.find((attr) => attr.name === 'size');
  button.innerText = sizeAttribute ? sizeAttribute.value['en-US'] : 'Select';
  button.onclick = () => {
    selectedVariant = variant;
    renderProductDetails(selectedVariant);
  };
  document.getElementById('variant-selector').appendChild(button);
});

// Initially render the master variant details
renderProductDetails(selectedVariant);

Key takeaways

• Master Variant as the default display: the masterVariant is always the primary variant returned by the API and should be shown by default when the product detail page loads. It includes essential product data like the main price, primary image, and core attributes—offering customers a complete and immediate view of the product before any interaction.
• Dynamic variant switching: allow users to interactively select from available variants (for example, size, color, or material). This interaction should trigger a real-time UI update to reflect the selected variant’s details—such as price, availability, and images—without requiring additional API calls, since all variant data is already included in the initial product projection response.
• Price context & Embedded Prices: when using Embedded Prices, the API response includes only those prices that match the specified context—such as priceCurrency, priceCountry, priceChannel, and storeProjection. This ensures that the displayed price is precise and relevant to the customer's regional and store-specific configuration.
• Inventory awareness: the availability field in the response provides both global and channel-specific stock levels. Use this information to enable or deactivate purchase options and to display accurate stock status messages (for example, In Stock, Out of Stock, or Available in Store X).
• Locale-driven data: the Product’s localized fields—such as name, description, and slug—are returned based on the specified localeProjection or Store configuration. This ensures that users see product content in their preferred language, enhancing both usability and regional relevance.

By understanding and leveraging how Product Variants are structured in the Product Projection API, you can deliver a highly interactive and personalized product detail page. Showing the Master Variant by default, combined with real-time variant switching, contextual pricing, inventory visibility, and localized content, ensures your product detail page provides a seamless and engaging shopping experience for every customer at Zen Electron.

Product media

Leveraging Composable Commerce’s robust asset management capabilities allows you to store, manage, and deliver these media assets efficiently—ensuring fast load times and a responsive user experience.

Images and assets belong to the variants and so each variant might have different images.

Pseudocode example (BFF/Frontend integration)

// Assume 'product' is the fetched product projection (For example, via fetchProductBySlug('charlie-armchair', 'en-US'))
const product = await fetchProductBySlug('charlie-armchair', 'en-US');
const masterVariant = product.masterVariant;

// Extract images from the master variant's assets field.
// If you also store videos, you can use masterVariant.assets.
const assets = masterVariant.images;

// Function to render assets on the product detail page.
function renderAssets(assets) {
  const container = document.getElementById('product-media-container');
  assets.forEach((asset) => {
    // Create an image element for each asset.
    const img = document.createElement('img');
    img.src = asset.url; // Set the image source URL.
    img.alt = product.name['en-US']; // Set an alt text using the product name.
    // Optionally, add interactive features such as zoom functionality.
    img.style.width = '100%'; // Adjust width as needed.
    container.appendChild(img);
  });
}

// Call the function to render the assets on the product detail page.
renderAssets(assets);

Test your knowledge