Do you find all information about us and our services?
Extensions by Category
📄 6. Advanced Topics & Troubleshooting
This section covers advanced configurations provided by JaJuMa WebP Optimized Images extension for unique edge cases and provides solutions for common compatibility challenges.
⚠️ Warning: The settings described here are for advanced users or for specific troubleshooting scenarios. For most standard Magento stores, these configurations are not needed.
🔑 6.1 Excluding Specific Images from WebP Conversion (Global Blacklist)
While the vast majority of images benefit from WebP conversion, you may have specific images you wish to exclude entirely. For example, a highly detailed technical diagram or a specific branded graphic that does not convert well.
The Blacklist setting in the
JaJuMa > WebP Image Optimization > Advanced Configuration
section allows you to prevent the extension from converting certain images.
- How it works:
Add a comma-separated list of strings or Regular Expressions. If an<img>tag's HTML matches any entry, it will be completely ignored by the extension, and the original<img>tag will be rendered without being wrapped in a<picture>element. - Examples:
- To exclude a logo by its filename:
logo\.png - To exclude all images added via the WYSIWYG editor:
wysiwyg - To exclude images with a specific CSS class:
product-image-photo
- To exclude a logo by its filename:
💡 Pro Tip: By default, the extension automatically excludes images within
media/captchaand any<img>tag that contains the attributedata-nowebp="true".
🔑 6.2 Ensuring Compatibility with Third-Party Lazy Loaders
A common challenge in the Magento ecosystem is ensuring compatibility between multiple extensions that modify the storefront. Many third-party themes and lazy loading extensions work by replacing the standard src and srcset attributes on <img> tags with custom attributes, such as data-src or data-srcset.
This can prevent our extension from finding the correct image URL to convert. The Custom src-/srcset-tags settings provide a powerful solution to this problem.
- Custom src-tag:
If your lazy load script uses a custom attribute for the main image source (e.g.,data-src), enter that attribute here. The extension will then look fordata-srcfirst to get the image URL for conversion. If not found, it will fall back to the standardsrcattribute. - Custom srcset-tag:
Similarly, if your script uses a custom attribute for the responsive image set (e.g.,data-srcset), enter it here. The extension will then generate the<picture>element usingdata-srcsetinstead of the standardsrcset.
⚠️ Warning: For this compatibility feature to work, you must ensure that your third-party lazy loading script is capable of handling the HTML
<picture>element. If your script only works with<img>tags, it may not be compatible.💡 Pro Tip: JS Lazy Loading is considered outdated and bad-practice.
We strongly recommend using native lazy loading instead and might deprecate JS lazy loading support in an upcoming release.
🔑 6.3 How to Use WebP for CSS Background Images
The extension automatically converts images rendered via HTML <img> tags. However, it cannot automatically convert images applied via CSS, such as background-image.
To solve this, the extension provides a clever CSS-based mechanism. It automatically adds a .no-webp class to the <body> tag of the page for any browser that does not support the WebP format. You can leverage this class to create a fallback in your custom CSS.
- Manually convert your background image to WebP format using an online tool or a local converter.
- Upload both the
.webpand the original (.jpgor.png) versions to your theme. - Update your CSS as follows:
/* Default rule for modern browsers */
.my-custom-section {
background-image: url('../images/my-background.webp');
}
/* Fallback rule for older browsers */
body.no-webp.my-custom-section {
background-image: url('../images/my-background.jpg');
}This approach ensures that all visitors see a background image, while modern browsers benefit from the smaller, faster-loading WebP version.
These troubleshooting steps cover the most common advanced issues. For a complete overview of all features and benefits, please refer to the main guide for WebP Optimized Images.
📞 Need Help?
Having trouble with the setup? Check our Troubleshooting, FAQ & Best Practices for common solutions.
Still have questions or need help verifying your system requirements? Our expert team is here to assist. Please don't hesitate to contact our support team for personalized assistance.
Ready to unlock these features for your store?
The JaJuMa WebP Optimized Images is the #1 WebP images solution for a faster, higher-ranking Magento store.
Find all you need to know and more valuable insights about Hyvä and Magento.
Expertly curated by JaJuMa:
🚀
Launch the JaJuMa Hyväverse
Your central resource for everything Hyvä.
Explore the Magento Metropolis!
Your central resource for everything Magento.
