npm package: @iftek/react-viewer
Description: react image/pdf viewer
Author: yuan9090
Latest version: 4.1.6

# @iftek/react-viewer

[![version](https://badge.fury.io/js/%40iftek%2Freact-viewer.svg)](https://www.npmjs.com/package/@iftek/react-viewer)
[![downloads](https://img.shields.io/npm/dt/@iftek/react-viewer.svg?style=flat-square)](https://npm-stat.com/charts.html?package=@iftek/react-viewer&from=2025-01-20)

- react image/pdf viewer.
- Fork from [react-viewer](https://github.com/infeng/react-viewer)
- Breaking change 3.x to 4.x : props `images` to `files`.

## Introduction

Because I can`t be comfortable using [viewerjs](https://github.com/fengyuanchen/viewerjs) in react, so I created react-viewer to replace it.

## Installation

> react >= 16.8.0 | react-dom >= 16.8.0

```bash
npm install @iftek/react-viewer --save
```

## Usage

```javascript
import * as React from 'react';
import Viewer from '@iftek/react-viewer';

function App() {
  const [ visible, setVisible ] = React.useState(false);

  return (
    <div>
      <button onClick={() => { setVisible(true); } }>show</button>
      <Viewer
      visible={visible}
      onClose={() => { setVisible(false); } }
      files={[{src: '', alt: ''}]}
      />
    </div>
  );
}
```

## Server Side (NextJS)

```
import React, { FC } from 'react'
import dynamic from 'next/dynamic'

const ReactViewer = dynamic(
  () => import('react-viewer'),
  { ssr: false }
)

export const Viewer: FC = () => {
  return (
    <ReactViewer
      visible={true}
      onClose={() => {}}
      files={[{src: ''}]}
    />
  )
}

export default Viewer
```

## Server Side rest..
I'm sorry, ssr is not currently supported in `4.x`, it will be fixed in `5.0`.

## Props

| props        | type         | default | description                 | required |
|--------------|--------------|---------|-----------------------------|----------|
| visible      | string       |  false  | Viewer visible             | true |
| onClose      | function       |  -      | Specify a function that will be called when Visible close   | true |
| files       | [FileDecorator](#filedecorator)[]     | []      | file source array | true  |
| activeIndex  | number       | 0       | active file 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   | wheather to show change button  | false |
| customToolbar | (defaultToolbarConfigs: [ToolbarConfig](#toolbarconfig)[]) => ToolbarConfig[] | - | customer toolbar | false |
| zoomSpeed    | number       | 0.05    | zoom speed | false |
| defaultSize    | [ViewerImageSize](#viewerimagesize) | - | default image size | false |
| defaultImg    | [viewerdefaultimg](#viewerimagesize) | - | if load img failed, show default img | 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 | (activeFile: [FileDecorator](#filedecorator), index: number) => void | - | callback when file 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 |

### FileDecorator

| props       | type         | default | description                 | required |
|-------------|--------------|---------|-----------------------------|----------|
| src  | string  |  -  | file source | true |
| alt  | string  |  -  | file description | false |
| downloadUrl  | string  |  -  | file downlaod url | false |
| defaultSize  | [ViewerImageSize](#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  | number  |  -  | 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 |

## 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

[npm-image]: https://badge.fury.io/js/react-viewer.svg
[npm-url]: https://npmjs.org/package/react-viewer