react-viewer
react image viewer.
Introduction
Because I can`t be comfortable using viewerjs in react, so I created react-viewer to replace it.
Installation
react >= 16.8.0 | react-dom >= 16.8.0
npm install react-viewer --save
Usage
import * as React from 'react';
import Viewer from 'react-viewer';
function App() {
const [ visible, setVisible ] = React.useState(false);
return (
<div>
<button onClick={() => { setVisible(true); } }>show</button>
<Viewer
visible={visible}
onClose={() => { setVisible(false); } }
images={[{src: '', alt: ''}]}
/>
</div>
);
}
Next.js (client-only)
react-viewer uses browser DOM APIs and must be loaded with SSR disabled. In the
Next.js App Router, put the dynamic import in a Client Component:
'use client';
import dynamic from 'next/dynamic';
const ReactViewer = dynamic(
() => import('react-viewer').then((mod) => mod.default),
{ ssr: false },
);
export default function Viewer() {
return (
<ReactViewer
visible={true}
onClose={() => {}}
images={[{src: ''}]}
/>
);
}
The Pages Router uses the same dynamic import but does not require the
'use client' directive. Direct server rendering is not supported in 3.x.
Props
| props |
type |
default |
description |
required |
| visible |
boolean |
false |
Viewer visible |
true |
| onClose |
function |
- |
Specify a function that will be called when Visible close |
true |
| images |
ImageDecorator[] |
[] |
image source array |
true |
| activeIndex |
number |
0 |
active image index |
false |
| zIndex |
number |
1000 |
Viewer css z-index |
false |
| container |
HTMLElement |
null |
set parent node(inline mode) |
false |
| drag |
boolean |
true |
whether to drag image |
false |
| attribute |
boolean |
true |
whether to show image attribute |
false |
| zoomable |
boolean |
true |
whether to show 'zoom' button |
false |
| rotatable |
boolean |
true |
whether to show 'rotate' button |
false |
| scalable |
boolean |
true |
whether to show 'scale' button |
false |
| onMaskClick |
(e) => void |
- |
callback function when mask is clicked |
false |
| downloadable |
boolean |
false |
whether to show 'download' |
false |
| noClose |
boolean |
false |
to not render close button |
false |
| noNavbar |
boolean |
false |
to not render the navbar |
false |
| noToolbar |
boolean |
false |
to not render the toolbar |
false |
| noImgDetails |
boolean |
false |
to not render image detail (WxH) |
false |
| noFooter |
boolean |
false |
to not render the entire footer |
false |
| changeable |
boolean |
true |
whether to show change buttons |
false |
| customToolbar |
(defaultToolbarConfigs: ToolbarConfig[]) => ToolbarConfig[] |
- |
customize the toolbar |
false |
| zoomSpeed |
number |
0.05 |
zoom speed |
false |
| defaultSize |
ViewerImageSize |
- |
default image size |
false |
| defaultImg |
ViewerDefaultImg |
- |
fallback shown when an image fails to load |
false |
| disableKeyboardSupport |
boolean |
false |
disable keyboard support |
false |
| noResetZoomAfterChange |
boolean |
false |
preserve zoom after image change |
false |
| noLimitInitializationSize |
boolean |
false |
no limit image initialization size |
false |
| defaultScale |
number |
1 |
set default scale |
false |
| onChange |
(activeImage: ImageDecorator, index: number) => void |
- |
callback when image change |
false |
| loop |
boolean |
true |
whether enable image loop |
false |
| disableMouseZoom |
boolean |
false |
whether disable mouse zoom |
false |
| downloadInNewWindow |
boolean |
false |
whether to download in a new window |
false |
| className |
string |
- |
customized CSS class |
false |
| showTotal |
boolean |
true |
whether to display the total number and range |
false |
| totalName |
string |
'of' |
total image separator name |
false |
| maxScale |
number |
- |
maximum scaling |
false |
| minScale |
number |
0.1 |
minimum scaling |
false |
| exportFileName |
string |
'exportFile' |
customize download's filename |
false |
ImageDecorator
| props |
type |
default |
description |
required |
| src |
string |
- |
image source |
true |
| alt |
string |
- |
image description |
false |
| downloadUrl |
string |
- |
image download URL |
false |
| defaultSize |
ViewerImageSize |
- |
image size |
false |
ViewerImageSize
| props |
type |
default |
description |
required |
| width |
number |
- |
image width |
true |
| height |
number |
- |
image height |
true |
ViewerDefaultImg
| props |
type |
default |
description |
required |
| src |
string |
- |
image source |
true |
| width |
number |
- |
image width |
false |
| height |
number |
- |
image height |
false |
ToolbarConfig
| props |
type |
default |
description |
required |
| key |
string |
- |
tool key |
true |
| render |
React.ReactNode |
- |
tool render |
false |
| onClick |
function |
- |
callback function when action is clicked |
false |
To keep only selected built-in controls, filter the configurations passed to
customToolbar. The key values are stable and avoid depending on numeric
actionType values:
<Viewer
visible={visible}
onClose={() => setVisible(false)}
images={images}
customToolbar={(toolbars) =>
toolbars.filter(({ key }) => key === 'zoomIn' || key === 'zoomOut')
}
/>
The returned array also controls the left-to-right order. For example, put
zoom out before zoom in while preserving the remaining controls and their
built-in actions:
<Viewer
visible={visible}
onClose={() => setVisible(false)}
images={images}
customToolbar={(toolbars) => [
...toolbars.filter(({ key }) => key === 'zoomOut'),
...toolbars.filter(({ key }) => key === 'zoomIn'),
...toolbars.filter(({ key }) => key !== 'zoomOut' && key !== 'zoomIn'),
]}
/>
Keep the original configuration objects so their actionType values are
preserved. Options such as zoomable={false} still hide the corresponding
controls.
Localizing the image counter
Use totalName to change the separator between the current image number and
the total. For example, this displays 1 / 3 for the first of three images:
<Viewer
visible={visible}
onClose={() => setVisible(false)}
images={images}
totalName="/"
/>
totalName="de" displays 1 de 3. The counter is visible by default;
showTotal={false} hides it. It is part of the image attribute row, so
attribute={false}, noToolbar, or noFooter also hides it.
Failed images
When an image URL fails to load, the viewer displays “Unable to load image.”
unless defaultImg supplies a fallback. The navigation and close controls remain
available, so users can continue to another image.
Keyboard support
Esc: Close viewer.
←: View the previous image.
→: View the next image.
↑: Zoom in the image.
↓: Zoom out the image.
Ctrl + 1: Reset the image.
Ctrl + ←: Rotate left the image.
Ctrl + →: Rotate right the image.
License
MIT