This article covers the most common issues and questions. If you do not find your answer here, open an issue on GitHub.
Zoom Issues
Zoom is not working on my image
The most common cause is that Zoomora’s smart zoom detection determined the image does not need zooming. Zoomora checks whether the image’s natural (actual file) dimensions are meaningfully larger than its rendered size in the lightbox. If the image already fits the viewport at or near its natural size, zoom is quietly disabled.
Things to check:
- Make sure
data-srcpoints to the full-size image, not a thumbnail - Remove any fixed
widthorheightHTML attributes from the<img>tag and use CSS sizing instead:
<!-- Avoid this -->
<img width="250" height="200" data-src="photo.jpg" data-zoomora="g" alt="">
<!-- Do this -->
<img style="width: 250px;" data-src="photo.jpg" data-zoomora="g" alt="">
- Make sure the full-size image file is actually larger than the lightbox viewport. A 400×300px image on a 1920×1080 screen will not qualify for zoom — there is nothing to zoom into.
The zoom button is visible but clicking it does nothing
This is the same cause as above — Zoomora detected the image is not zoomable and silently disabled the zoom action. The button remains visible but does nothing. Check the three points above.
showZoom: false is not hiding the zoom button
This was a bug in versions prior to v1.2.1. Update to the latest version:
npm install zoomora@latest
Thumbnail Issues
showThumbnails: false is not hiding the thumbnail strip
This was a bug in versions prior to v1.2.1. Update to the latest version:
npm install zoomora@latest
The thumbnail strip is showing for a single image
Zoomora should hide thumbnails automatically for single-item galleries. If you are seeing a thumbnail strip for a single image, check that no other images on the page share the same data-zoomora value — Zoomora groups all elements with matching values regardless of where they appear in the DOM.
Counter & Button Issues
showCounter: false / showFullscreen: false is not working
This was a bug in versions prior to v1.2.1 affecting all four show* options. Update to the latest version:
npm install zoomora@latest
Icon / Font Issues
Icons are not appearing or showing as squares
This usually means the icon font has not loaded yet when the lightbox opened. Make sure zoomora.css is loaded in <head> — not deferred or loaded asynchronously:
<head>
<link rel="stylesheet" href="zoomora.css"> <!-- must be in head -->
</head>
If you are loading via npm and a bundler, make sure the CSS import is at the top of your entry file:
import 'zoomora/dist/zoomora.css'; // import CSS first
import Zoomora from 'zoomora';
Firefox shows a font glyph bounding box warning in the console
This was a known issue in versions prior to v1.2.1 caused by incorrect metadata in the icon font file. It was a Firefox-only warning and did not cause any visual breakage. Fixed in v1.2.1 — update to clear it:
npm install zoomora@latest
Video Issues
YouTube video is not loading
Check that the URL format is correct. Both standard and short formats are supported:
https://www.youtube.com/watch?v=VIDEO_ID ✅
https://youtu.be/VIDEO_ID ✅
https://youtube.com/embed/VIDEO_ID ✅
Also make sure data-type="video" is set on the element — without it Zoomora treats the URL as an image.
Local video is not playing
Check that the video file format is supported by the user’s browser. MP4 (H.264) has the widest support. Also verify the file path in data-src is correct and the file is accessible from the page.
WordPress Issues
Zoomora is not initialising in WordPress
Make sure the script is loaded in the footer (fifth argument true in wp_enqueue_script) and that new Zoomora() is called inside a DOMContentLoaded listener:
wp_enqueue_script('zoomora', $src, [], '1.2.1', true);
wp_add_inline_script('zoomora', '
document.addEventListener("DOMContentLoaded", function() {
new Zoomora();
});
');
Zoomora conflicts with another lightbox plugin
If your theme or another plugin also loads a lightbox (Fancybox, Lightbox2, etc.), they may both try to handle the same elements. Fix this by either:
- Dequeuing the other lightbox plugin
- Limiting Zoomora’s selector to specific elements only:
new Zoomora({ selector: '[data-zoomora]' });
Make sure the conflicting plugin does not also target elements with data-zoomora attributes.
General Questions
Does Zoomora work without a build tool or bundler?
Yes. Use the CDN or download the UMD build and include it with a <script> tag. No Node.js or bundler required:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/zoomora/dist/zoomora.css">
<script src="https://cdn.jsdelivr.net/npm/zoomora/dist/zoomora.umd.min.js"></script>
<script>new Zoomora();</script>
Does it work with React or Vue?
Yes. Install via npm and import as an ES module. Initialise in a useEffect (React) or mounted (Vue) hook and call destroy() on unmount to clean up:
// React
useEffect(() => {
const lightbox = new Zoomora();
return () => lightbox.destroy();
}, []);
// Vue
mounted() {
this.lightbox = new Zoomora();
},
beforeUnmount() {
this.lightbox.destroy();
}
Can I use Zoomora in a commercial project?
Yes. Zoomora is MIT licensed — free for personal, client, and commercial projects with no royalties or license keys. The only requirement is that the original copyright notice is retained in distributed source files.
Which browsers are supported?
All modern browsers: Chrome, Firefox, Safari, and Edge (latest versions), including iOS Safari and Chrome for Android. Internet Explorer is not supported.
How do I report a bug or request a feature?
Open an issue on GitHub. Please include:
- Your browser and version
- Zoomora version (
npm list zoomoraor check yourpackage.json) - A minimal reproduction (CodePen or JSFiddle works well)
- What you expected vs what happened
Feature requests are welcome — label them with the enhancement tag.
How do I contribute?
Contributions are welcome. Fork the repository, create a feature branch, make your changes, and open a pull request on GitHub. Please include a clear description of what you changed and why.