Summary

react-zmage provides a zero-configuration, drop-in solution for transforming standard <img> elements into a fullscreen, keyboard-navigable image viewer within React applications. It targets React developers seeking an easy-to-integrate, flexible image viewing component that supports Server-Side Rendering (SSR) and React Server Components (RSC).

How It Works

The library offers three primary integration patterns: a declarative component that accepts native <img> props, an imperative API (Zmage.browsing()) for programmatic control, and a <Zmage.Wrapper> component that automatically enhances all <img> tags within a given subtree. This wrapper is particularly useful for rendering uncontrolled HTML content like markdown or rich text. A dedicated react-zmage/ssr entry point ensures SSR/RSC compatibility by avoiding browser-specific APIs at import time, making it safe for server environments.

Quick Start & Requirements

Install via package managers: pnpm add react-zmage. Peer dependencies include react@>=16.8 <20 and react-dom@>=16.8 <20. The library auto-detects and utilizes React 18+'s createRoot API when available. For SSR/RSC environments, import from react-zmage/ssr. Verified against Next.js 15 App Router and Vite SSR.

Highlighted Details

• Seamlessly replaces <img> tags, forwarding all native HTML attributes.
• SSR/RSC safe build (react-zmage/ssr) prevents document access during module load.
• Flexible usage: component, imperative calls, or wrapper for auto-binding images in dynamic content.
• Supports multi-image galleries and custom captions.
• Extensive customization options for UI controls, keyboard shortcuts, animations, and styling.

Maintenance & Community

The project is structured as a pnpm + turbo monorepo, with contributions guided by AGENTS.md for architectural invariants. No specific community channels or contributor details were found in the provided text.

Licensing & Compatibility

Released under the MIT license, permitting broad use in commercial and closed-source applications. Compatible with React versions 16.8 through 19.

Limitations & Caveats

In <Zmage.Wrapper> mode, images dynamically added to the DOM after the wrapper mounts will not be automatically bound until the wrapper re-renders. The imperative Zmage.browsing() function should be guarded with typeof window !== 'undefined' for server-side execution.