react-viewer

library3.2.2jsnpmunverified

react-viewer is a dedicated image viewing component for React applications, providing a customizable and feature-rich lightbox experience. It is currently in version 3.2.2 and sees active development with frequent minor releases addressing bugs and adding features. A major version 4.0 is planned to re-introduce Server-Side Rendering (SSR) support. Key differentiators include its native React implementation, utilizing React Hooks and `ReactDOM.createPortal` for modern React patterns, offering a robust alternative to general-purpose JavaScript viewer libraries like Viewer.js within a React ecosystem. It supports various image operations like zooming, rotating, scaling, and offers extensive customization through props for toolbar, navbar, and general UI behavior. It ships with TypeScript type definitions.

web-framework

npm install react-viewer

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-VIEWER

react-viewer

web-frameworkjavascriptv3.2.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Viewer

✓ import Viewer from 'react-viewer';

✗ import { Viewer } from 'react-viewer';

The Viewer component is a default export.

ViewerProps

✓ import type { ViewerProps } from 'react-viewer';

Type import for the Viewer component's props, useful for TypeScript projects.

styles

✓ import 'react-viewer/dist/index.css';

✗ import 'react-viewer/assets/index.css';

CSS import path changed in v3.2.0; necessary for correct styling. Previous versions (pre-v3.0.0 and v3.2.0 specifically) had different CSS import requirements. v3.2.1 reverted to CSS-in-JS, making this external import redundant, but v3.2.0 explicitly required it.

This quickstart demonstrates how to integrate react-viewer into a functional React component, using state to control the viewer's visibility and passing an array of image objects. It includes basic interaction props for zoom, rotate, and download.

import * as React from 'react'; import Viewer from 'react-viewer'; function App() { const [visible, setVisible] = React.useState(false); const images = [ { src: 'https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885_1280.jpg', alt: 'Forest' }, { src: 'https://images.unsplash.com/photo-1507525428034-b723cf961c3e', alt: 'Beach' } ]; return ( <div> <button onClick={() => { setVisible(true); } } style={{ padding: '10px 20px', fontSize: '16px', cursor: 'pointer' }}> Show Images </button> <Viewer visible={visible} onClose={() => { setVisible(false); } } images={images} activeIndex={0} downloadable={true} zoomable={true} rotatable={true} scalable={true} noFooter={false} /> </div> ); }

Debug

Known issues

breakingVersion 3.0.0 introduced significant breaking changes by refactoring with React Hooks and replacing `ReactDOM.unstable_renderSubtreeIntoContainer` with `ReactDOM.createPortal`. This requires React and React-DOM versions 16.8.0 or newer. Prior React versions are incompatible.

fix

Ensure `react` and `react-dom` are updated to version `16.8.0` or higher. Refactor class components using `react-viewer` to functional components if needed to leverage Hooks effectively, or adjust prop usage.

affects: >=3.0.0

breakingServer-Side Rendering (SSR) is not supported in any 3.x version of `react-viewer`. While version 3.2.0 attempted to re-enable SSR by extracting CSS, this was quickly reverted in 3.2.1 due to issues. Full SSR support is targeted for version 4.0.

fix

Avoid using `react-viewer` in SSR contexts with 3.x. If SSR is critical, consider conditional rendering to only mount `react-viewer` on the client-side or wait for the 4.0 release. Consult the roadmap for 4.0 development.

affects: >=3.0.0 <4.0.0

breakingThe method of importing CSS changed between `v3.0.0`, `v3.2.0`, and `v3.2.1`. Version 3.0.0 moved to 'css-in-js', removing the need for an external CSS import. Version 3.2.0 re-extracted CSS requiring `import 'react-viewer/dist/index.css'`. Version 3.2.1 reverted to css-in-js, making the external import unnecessary again. This frequent change can cause styling issues.

fix

For versions `3.0.x` and `>=3.2.1`, no explicit CSS import is generally needed as styles are bundled or injected. For `v3.2.0` specifically, ensure `import 'react-viewer/dist/index.css';` is present. Always test styling carefully after `react-viewer` updates.

affects: >=3.0.0 <3.2.2

Errors

Common errors & fixes

Error: Invalid hook call. Hooks can only be called inside of the body of a functional component.

Using `react-viewer` v3.0.0 or later with an older version of React (pre-16.8.0).

fix

Upgrade `react` and `react-dom` packages to version `16.8.0` or higher.

SyntaxError: Unexpected token 'export' (for ESM usage in Node.js/CJS environment)

`react-viewer` is primarily an ESM module for modern React projects, leading to issues when directly `require()`d in a CommonJS-only Node.js environment without proper transpilation or configuration.

fix

Ensure your project build setup (e.g., Webpack, Babel) correctly handles ESM modules, especially if targeting older Node.js versions or CommonJS. For client-side React apps, this is usually handled automatically. If running server-side, you might need to configure your bundler to transpile `node_modules`.

The image viewer opens but appears unstyled or with incorrect layout.

Incorrect or missing CSS import, especially for `v3.2.0` where an external CSS import was temporarily required before reverting to CSS-in-JS.

fix

For `react-viewer@3.2.0`, add `import 'react-viewer/dist/index.css';` to your entry point. For `v3.0.x` and `>=3.2.1`, this import is typically not needed, as styles are handled internally. Check the `react-viewer` release notes for your exact version to confirm CSS import requirements.

Upgrade

Version history

3.2.2latest on npm

Audit

Dependencies

reactrequiredPeer dependency, required for component functionality.

react-domrequiredPeer dependency, required for rendering with React Portals.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/infeng/react-viewer ↗

packagehttps://www.npmjs.com/package/react-viewer ↗