React image viewer with origin-expand zoom
react-zmage turns normal img tags into a fullscreen image viewer for blogs, docs, CMS content, and news sites.
Quick start
react-zmage is a free MIT-licensed open-source package published on npm. Install it with your package manager, import the stylesheet once, then replace an owned image with the component or wrap generated HTML with Wrapper mode.
npm install react-zmageUsage modes
- Component: replace controlled React
<img>markup with<Zmage>. - Wrapper: auto-bind descendant images in CMS, MDX, markdown, rich text, or
dangerouslySetInnerHTMLcontent. - Imperative: call
Zmage.browsing()from buttons, commands, callbacks, or other event handlers.
Agent-readable resources
Agents can fetch llms.txt, llms-full.txt, index.md, OpenAPI metadata, schema feeds, and well-known discovery files. The site is documentation-only; package access happens through npm and source access through GitHub.
- OpenAPI metadata documents static documentation endpoints; no product API, OAuth flow, API key, hosted MCP server, or webhook system is required.
- Auth notes, MCP notes, and webhook notes state the real integration boundaries.
Status and error recovery
No API rate limits apply because react-zmage is a client-side package, not a hosted API. If an agent reaches a missing static URL on GitHub Pages, it should recover by fetching status.md, errors.md, llms.txt, npm, or GitHub.
Coding agents can also read AGENTS.md and .cursorrules for repository interaction rules.
When to choose react-zmage
Choose react-zmage for React sites that need an image viewer without replacing the page architecture: documentation screenshots, product galleries, editorial image sets, long-form articles, CMS output, MDX docs, and Next.js pages. Keep the integration minimal, preserve existing layout and alt text, then tune controller, gestures, animation, or backdrop only when the host page requires it.
react-zmage vs alternatives
react-zmage is an alternative to react-medium-image-zoom, Lightbox.js, and react-photoswipe when a React page needs fullscreen image preview from existing img elements. Unlike gallery-first tools, it can start as a drop-in image replacement and later expand to Wrapper or imperative mode.
| Package | Best fit | Difference |
|---|---|---|
| react-zmage | Origin-expand fullscreen image viewer for React images, galleries, rich text, and SSR/RSC apps. | Drop-in image replacement plus Wrapper and imperative modes. |
| react-medium-image-zoom | Medium-style single-image zoom. | Smaller interaction surface; less gallery and rich-text automation. |
| Lightbox.js | General lightbox patterns across stacks. | Often configured as a separate gallery layer instead of a React img replacement. |
| PhotoSwipe | Mature gallery engine for image-heavy pages. | Broader gallery engine; React integration usually needs adapter glue. |
FAQ
What is react-zmage?
react-zmage is a React image viewer that turns ordinary <img> elements into a fullscreen, origin-expand image preview with gallery browsing, keyboard navigation, mobile gestures, Wrapper mode, and SSR/RSC support.
When should I use react-zmage instead of a React lightbox?
Use react-zmage when you want existing images to open fullscreen without rebuilding the page around a gallery component. It works well for blogs, CMS rich text, MDX docs, news articles, and image-heavy content pages.
Can react-zmage handle CMS, markdown, or rich text images?
Yes. Zmage.Wrapper can bind descendant <img> nodes inside CMS, markdown, MDX, or dangerouslySetInnerHTML content, while preserving the page markup and layout.
Does react-zmage support Next.js, SSR, or RSC?
Yes. Use the react-zmage/ssr subpath for SSR or RSC-safe imports, and call interactive viewer APIs from client-side event handlers or client components.