docusaurus-theme-zoom-image

Hover magnifier + full-screen lightbox for every Markdown image on your Docusaurus site. One line of config, zero dependencies.

Why

I write tutorials with a lot of terminal screenshots, and they render small. Readers were squinting. The existing zoom plugins pull in a dependency for what is essentially one component and a bit of CSS — so I wrote the component and shipped it as a theme you can drop into any site.

What you get

• 🔍 Hover affordance — zoom cursor plus a magnifier badge, so readers know the image is clickable
• 🖼️ Full-screen lightbox — dark backdrop, image up to 96 % of the viewport, sharp at native resolution
• ⌨️ Keyboard + scroll handling — Esc closes, page scroll locks while open, click anywhere to dismiss
• 🪶 Zero dependencies — nothing beyond Docusaurus and React themselves; ~120 lines of code you can read in one sitting
• ✍️ Zero content changes — every ![alt](image.png) in docs, blog and pages just works; your own React components are left alone

Compatibility

| Docusaurus | Status | |---|---| | 3.x | ✅ supported | | 2.x | untested — the @theme-init pattern exists there, reports welcome |

Installation

npm install docusaurus-theme-zoom-image

// docusaurus.config.js
export default {
  themes: ['docusaurus-theme-zoom-image'],
};

That's the whole setup. The theme registers itself as the MDX img component, so every Markdown image becomes zoomable at build time — no wrappers, no imports in your content.

Customizing

The styles are plain CSS with stable class names — override any of them from your site's custom.css:

| class | what it is | |---|---| | zoomImage | the inline image | | zoomImage__badge | the hover magnifier badge | | zoomImage__overlay | the full-screen backdrop | | zoomImage__full | the enlarged image | | zoomImage__close | the × button |

Need to change behavior rather than looks? Swizzle it:

npm run swizzle docusaurus-theme-zoom-image ZoomImage

Opting an image out

Only Markdown-syntax images are enhanced. Write a plain HTML <img> tag in your MDX and it's left untouched. Images rendered inside your own React components are never affected.

How it works

Docusaurus lets themes contribute MDX components. This theme shadows MDXComponents via @theme-init — the stackable variant — and maps img to a small React component that renders your image unchanged, plus the badge and a portal-free overlay. Because it wraps @theme-init, other themes still apply and your site's own src/theme overrides always win.

Contributing

Issues and PRs welcome. The whole theme is three small files under src/theme/ — if you can read React, you can review all of it in five minutes.

License

MIT