Magento 2: Hide Base Image On Custom Option Image Selection

Oct 8, 2025 by ADMIN 60 views

Hide Base Image When Custom Option Images Selected (Simple Product Magento 2)

Hey guys! Today, we're diving into a cool little customization for your Magento 2 store. Ever wanted to hide that base product image when your customers select custom options that come with their own images? It's all about giving a cleaner, more focused look at what they're actually choosing. Let's get this done!

Understanding the Goal

Okay, so the main idea here is to make sure that the default or base image of your simple product disappears from the product image gallery as soon as a customer selects a custom option that has its own associated image. Why do this? Well, it reduces clutter and makes the visual experience way more intuitive. Imagine you're selling a t-shirt, and customers can choose different prints. When they select a print, you want that print to be the star of the show, not the plain t-shirt it's going on.

This involves a bit of JavaScript magic combined with Magento's templating system. We're essentially going to listen for changes in the custom options, and when an option with an image is selected, we'll hide the base image. It's all about creating a dynamic and responsive user interface. This isn't just about aesthetics; it's about guiding your customers through the selection process and ensuring they see exactly what they're adding to their cart. Plus, it can seriously reduce confusion and boost those conversion rates! We'll take a look at how to implement this step-by-step, so even if you're not a coding whiz, you can follow along and get your Magento 2 store looking slick.

Step-by-Step Implementation

Step 1: Create a Custom Module

First things first, we're going to create a custom module. If you already have one, great! If not, follow these steps:

Create a directory structure: app/code/YourVendor/YourModule

Create a module.xml file in app/code/YourVendor/YourModule/etc/:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="YourVendor_YourModule" setup_version="1.0.0">
    </module>
</config>

Create a registration.php file in app/code/YourVendor/YourModule/:

<?php
use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'YourVendor_YourModule',
    __DIR__
);

Don't forget to replace YourVendor and YourModule with your actual vendor and module names. Once you've done that, run php bin/magento setup:upgrade to register your module.

Step 2: Create a Layout Update

Next, we need to add some JavaScript to the product view page. We'll do this by creating a layout update file.

Create a catalog_product_view.xml file in app/code/YourVendor/YourModule/view/frontend/layout/:

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceBlock name="product.info.media.gallery">
            <arguments>
                <argument name="jsLayout" xsi:type="array">
                    <item name="components" xsi:type="array">
                        <item name="gallery" xsi:type="array">
                            <item name="config" xsi:type="array">
                                <item name="template" xsi:type="string">YourVendor_YourModule/gallery</item>
                            </item>
                        </item>
                    </item>
                </argument>
            </arguments>
        </referenceBlock>
    </body>
</page>

This layout update tells Magento to use our custom template for the product image gallery.

Step 3: Create the Custom Template

Now, let's create the custom template file.

Create a gallery.phtml file in app/code/YourVendor/YourModule/view/frontend/templates/:

<div class="product media" data-gallery-role="gallery-container">
    <div class="fotorama" data-gallery-role="gallery" data-mage-init='{"YourVendor_YourModule/js/gallery": {}}">
        <?php foreach ($block->getGalleryImages() as $image):
            $imageurl = $image->getData('url');
            $isBaseImage = $image->getData('is_base');
            ?>
            <img src="<?php echo $imageurl; ?>" alt="<?php echo $block->escapeHtml($image->getLabel()); ?>" data-is-base="<?php echo $isBaseImage ? '1' : '0'; ?>">
        <?php endforeach; ?>
    </div>
</div>

This template loops through the product images and adds a data-is-base attribute to each image, which we'll use in our JavaScript.

Step 4: Add the JavaScript

Time for the JavaScript that does the magic. Create a JavaScript file.

Create a gallery.js file in app/code/YourVendor/YourModule/view/frontend/web/js/:

define([
    'jquery',
    'mage/utils/wrapper',
    'Magento_Catalog/js/product/data',
    'jquery/ui',
    'fotorama/fotorama'
], function ($, wrapper, productData) {
    'use strict';

    return function (config, element) {
        var self = this;
        var isBaseImageVisible = true;

        $(document).on('change', '.product-custom-option', function () {
            var selectedOption = $(this);
            var hasImage = selectedOption.find('option:selected').data('image');

            if (hasImage && isBaseImageVisible) {
                $(element).find('img[data-is-base="1"]').hide();
                isBaseImageVisible = false;
            } else if (!hasImage && !isBaseImageVisible) {
                $(element).find('img[data-is-base="1"]').show();
                isBaseImageVisible = true;
            }
        });
    };
});

This JavaScript code listens for changes in the custom options. If a selected option has an image, it hides the base image. If the selected option doesn't have an image, it shows the base image again.

Step 5: Configure Custom Options

Finally, you need to configure your custom options to include image data. When creating or editing a custom option, add a data attribute to the <option> tag with the image URL:

<select class="product-custom-option" name="options[123]">
    <option value="1" data-image="/path/to/image1.jpg">Option 1</option>
    <option value="2" data-image="/path/to/image2.jpg">Option 2</option>
    <option value="3">Option 3</option>
</select>

Clearing the Cache

After all these steps, don't forget to clean the cache using the following command:

php bin/magento cache:clean
php bin/magento cache:flush

This ensures that all the changes you've made are correctly applied and visible on your store.

Final Thoughts

And there you have it! By following these steps, you can dynamically hide the base image when custom option images are selected, providing a cleaner and more intuitive experience for your customers. Remember to test thoroughly and adjust the code to fit your specific needs. Happy coding, and may your Magento store shine!