Skip to content

Commit

Permalink
Merge pull request #115 from manav-gopal/master
Browse files Browse the repository at this point in the history 
Migration of iv-viewer to react-img-viewer (React Library)
  • Loading branch information
@s-yadav
s-yadav committed Jun 23, 2024
2 parents 0df0723 + d7400f1 commit b7bcc8f
Show file tree
Hide file tree
Showing 71 changed files with 11,686 additions and 3,516 deletions.
18 changes: 9 additions & 9 deletions .all-contributorsrc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,6 @@
"commit": true,
"commitConvention": "none",
"contributors": [
{
"login": "ruchikabgosain",
"name": "Ruchika",
"avatar_url": "https://avatars2.githubusercontent.com/u/30324532?v=4",
"profile": "http://mozillians.org/en-US/u/ruchikabgosain/",
"contributions": [
"doc"
]
},
{
"login": "s-yadav",
"name": "Sudhanshu Yadav",
Expand All @@ -45,6 +36,15 @@
"contributions": [
"doc"
]
},
{
"login": "ruchikabgosain",
"name": "Ruchika",
"avatar_url": "https://avatars2.githubusercontent.com/u/30324532?v=4",
"profile": "http://mozillians.org/en-US/u/ruchikabgosain/",
"contributions": [
"doc"
]
}
],
"contributorsPerLine": 7
Expand Down
29 changes: 29 additions & 0 deletions .github/workflows/main.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
name: CI
on: [push]
jobs:
build:
name: Build, lint, and test on Node ${{ matrix.node }} and ${{ matrix.os }}

runs-on: ${{ matrix.os }}
strategy:
matrix:
node: ['18.x','20.x']
os: [ubuntu-latest, windows-latest, macOS-latest]

steps:
- name: Checkout repo
uses: actions/checkout@v2

- name: Use Node ${{ matrix.node }}
uses: actions/setup-node@v1
with:
node-version: ${{ matrix.node }}

- name: Install deps and build (with cache)
uses: bahmutov/npm-install@v1

- name: Lint
run: yarn workspace react-iv-viewer lint

- name: Build
run: yarn build
274 changes: 63 additions & 211 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,250 +1,102 @@
# iv-viewer
[![All Contributors](https://img.shields.io/badge/all_contributors-4-orange.svg?style=flat-square)](#contributors-)
A zooming and panning plugin inspired by google photos for your web images.

### Features
<ul>
<li>Smooth dragging and panning of images.</li>
<li>Support touch devices.</li>
<li>Double tap to zoom in/zoom out.</li>
<li>Pinch in/out to control zoom.</li>
<li>Snap view for better panning and zooming experience.</li>
<li>Allow quick display of loaded image then loading of high quality image progressively.</li>
<li>Exposed API to control zoom programmatically.</li>
<li>Custom Events to listen for the state changes.</li>
</ul>

![alt tag](assets/imageviewer.jpg)

### Install
Through npm
```
npm install iv-viewer --save
```

Or get compiled development and production version (css and js) from ./dist

### Usage
Import ImageViewer and it's style.
```js
import ImageViewer from 'iv-viewer';

// or
const ImageViewer = require('iv-viewer').default;

// Import css
import 'iv-viewer/dist/iv-viewer.css';
```
You can choose to import css file inside your scss/less files.

You can also use the standalone UMD build by including dist/iv-viewer.js and dist/iv-viewer.css in your page.
```html
<script src="https://unpkg.com/iv-viewer/dist/iv-viewer.js"></script>

<link rel="stylesheet" href="https://unpkg.com/iv-viewer/dist/iv-viewer.css">
```

### Three different modes

#### Full-Screen Mode
If you want to show images in full screen, with predefined styles. You can use FullScreenViewer.
```js
import { FullScreenViewer } from 'iv-viewer';
# iv-viewer
___

const viewer = new FullScreenViewer(options); // check options section for supported options
A zooming and panning plugin inspired by Google Photos for your web images. It comes in two different variants. First, a react-based zooming and panning component and 2nd vanilla JS-based zooming and panning library.

viewer.show('images/low-res-img', 'images/hi-res-img'); //second option is optional. Check better image loading section
```
## react-iv-viewer

#### Container Mode
If you have your own container to show images (you might have custom layout or gallery), you can use image-viewer in a container mode.

```html
<div id="image-container"></div>
```
`react-iv-viewer` is a React-based library for viewing images with advanced features like zooming, high-resolution image support, and full-screen viewing. It provides an easy way to integrate image viewing functionality into your React applications.

```js
import ImageViewer from 'iv-viewer';
### Features

const container = document.querySelector('#image-container');
const viewer = new ImageViewer(container, options); //check options section for supported options
- Smooth dragging and panning of images
- Support for touch devices
- Double tap to zoom in/zoom out
- Pinch in/out to control zoom
- Zooming with mouse wheel or buttons
- High-resolution image support
- Full-screen image viewing
- Customizable viewer dimensions
- TypeScript support

viewer.load('images/low-res-img', 'images/hi-res-img'); //second option is optional. Check better image loading section
```
### Demos

#### Image Mode
If you just want to add zoom and pan gesture to your images in a image-viewer style, you can use image-viewer in image mode.
```html
<img id="image" src="image.png" data-high-res-src="hi-res-image.png" />
```
See the many DEMO sections in the documentation.

```js
import ImageViewer from 'iv-viewer';
### Install

const image = document.querySelector('#image');
const viewer = new ImageViewer(image, options); // check options section for supported options
using `npm`
```bash
npm install react-iv-viewer
```

### Options
| Option | Allowed Value | Default | Description |
| ------------- |-------------| -----| -------- |
| zoomValue | number in percentage | 100 | It defines the initial zoom value of the image. |
| maxZoom | number in percentage | 500 | It defines the max limit for the zoom value of the image. |
| snapView | boolean | true | If true will show snap view. |
| refreshOnResize | boolean | true | Defines whether to refresh the viewer on resize of window. This is available only for Container and Image mode. On FullScreen mode it will refresh on window resize by default.|
| zoomOnMouseWheel | boolean | true | Defines weather to allow zoom with mouse scroll or not. |
| hasZoomButtons | boolean | true | Defines weather to add zoom buttons or not |
| zoomStep | number | 50 | The number of which the zoom should increase/decrease when the buttons are clicked |
| listeners | object | null | multiple useful callbacks that could use in-order to get the current state of the viewer|

### The Listeners
There are multiple listeners you can register with each viewer instance
```js
import ImageViewer from 'iv-viewer';

const viewer = new ImageViewer(element, {
listeners: {
onInit: callback(data), // called when the instance is initiated
onDestroy: callback(), // called when the instance is destroyed
onImageLoaded: callback(data), // called on image load
onZoomChange: callback(data), // called on zoom in/out
}
});
using `yarn`
```bash
yarn add react-iv-viewer
```
### Callback Data
The data passed to each callback is very useful, it contains the current instance with more info that you can use to react to the instance state

| Option | dataType | Description |
| ------------- |-------------| -------- |
| container | HTMLElement | The current container of the viewer |
| snapView | HTMLElement | The snap view element in the viewer |
| zoomValue | Number | The current zoom value |
| reachedMin | boolean | A boolean value that determine if the zoom value reached the initial zoom.|
| reachedMax | boolean | A boolean value that determine if the zoom value reached the maximum zoom. |
| instance | ImageViewer | The current instance which contains all other info if needed |

### API (ImageViewer)
#### ES6

Creating an instance

```js
import ImageViewer from 'iv-viewer';

const viewer = new ImageViewer(element, options);
Image Viewer
```jsx
import { ImageViewer } from 'react-iv-viewer';
```
Here the first argument is the element, which can be container where viewer will be loaded, or it can be a image in which case viewer will be initialized in a image mode.

You can also pass a selector directly instead of a DOM element.
```js
const viewer = new ImageViewer('#element', options);
Fullscreen Viewer
```jsx
import { FullScreenImageViewer } from 'react-iv-viewer';
```

Second argument is to provide configuration options for the ImageViewer. This argument is optional.

#### Instance methods
**load(imgSrc, highResImg)**
## iv-viewer
___

Load an image to the viewer. You can pass two different resolution of the image as first and second argument (optional). See why do you need it at [better image loading](#better-image-loading) section.
`iv-viewer` is a zooming and panning plugin inspired by Google Photos for your web images. It provides a smooth and intuitive way to view images with features like full-screen mode, touch device support, and high-resolution image loading.

```js
viewer.load('image.png', 'hi-res-image.png');
```
Note that this is just required for the container mode, as in image mode you can just use `src` and `data-high-res-src` attribute and the image will load by itself. See [image mode](#image-mode) example

**zoom(zoomValue, point)**
### Features

zoomValue: A percentage value to which you want to zoom the image.
- Smooth dragging and panning of images
- Support for touch devices
- Double tap to zoom in/zoom out
- Pinch in/out to control zoom
- Snap view for better panning and zooming experience
- Quick display of loaded images with progressive loading of high-quality images
- Exposed API to control zoom programmatically
- Custom events to listen for state changes

point(optional): Point {x, y} is the coordinate of the container which would act as the center for the zoom. If not defined, it will take the center of the container as the zooming point.
### Install

```js
viewer.zoom(300, { x: 500, y: 500 });
Using `npm`
```bash
npm install iv-viewer --save
```

**resetZoom()**

Reset zoom to the default or provided initial zoomValue.

```js
viewer.resetZoom();
Using `yarn`
```bash
yarn add iv-viewer
```

**refresh()**

Method to manually refresh the viewer. It will reset the zoom and pan. It will also recalculate the dimension of container, window and image in case if that is changed.
```js
viewer.refresh();
```
## Usage
### ES6
Image Viewer
```jsx
import ImageViewer from 'iv-viewer';
import 'iv-viewer/dist/iv-viewer.css';

**destroy()**
const container = document.querySelector('#image-container');
const viewer = new ImageViewer(container, options);

Destroys the plugin instance and unbind all events. It will also reset the container or the image(if ImageViewer is used in image mode). It returns null which you should assign to viewer variable to completely free up memory.
```js
viewer = viewer.destroy();
viewer.load('images/low-res-img', 'images/hi-res-img');
```

### API (FullScreenViewer)
FullScreenViewer is extended from ImageViewer. So it shares the same ImageViewer api along with some FullScreenViewer API.

Creating an instance

```js
Fullscreen Viewer
```jsx
import { FullScreenViewer } from 'iv-viewer';
import 'iv-viewer/dist/iv-viewer.css';

const viewer = new FullScreenViewer(options);
```
Unlike ImageViewer you don't have to pass container for the viewer as it will be initialized in pre-defined full screen container.

First argument is to provide configuration options for the FullScreenViewer. This argument is optional.

#### Instance methods (FullScreenViewer)
FullScreenViewer inherits all the instance method of ImageViewer. In additional to that it has following methods.

**show(imgSrc, highResImg)**

Show the full screen viewer with passed image on the show method. You can pass two different resolution of the image as first and second argument (optional). See why do you need it at [better image loading](#better-image-loading) section.

```js
viewer.show('image.png', 'hi-res-image.png');
```

**hide()**

Hide/Close the fullScreen viewer.
```js
viewer.hide();
```

### Better image loading
To improve the perceived experience, it is always recommended to show the already loaded image or the low quality image on the viewer and let the ImageViewer load high quality image in parallel.

It will also try to preview the high quality image while it's loading so it will give a progressive loading effect.

ImageViewer provides api to do this.
Container mode
```js
viewer.load('image.png', 'hi-res-image.png');
```

FullScreen mode
```js
viewer.show('image.png', 'hi-res-image.png');
```

Image Mode
```html
<img id="image" src="image.png" data-high-res-src="hi-res-image.png" />
viewer.show('images/low-res-img', 'images/hi-res-img');
```

In all of the above example it will first try to display the first image and then load the second image (if passed) in parallel.

The second image is optional, which you should pass when you feel you can improve the image loading experience by first showing low quality image and then progressively update it with high quality image.

### Demo
codesandbox preview link: [https://8ypwzryom0.codesandbox.io/](https://8ypwzryom0.codesandbox.io/)

codesandbox link: [https://codesandbox.io/s/8ypwzryom0](https://codesandbox.io/s/8ypwzryom0)

### Like this
[:star: this repo](https://github.com/s-yadav/iv-viewer)

Expand Down
1 change: 0 additions & 1 deletion dist/iv-viewer.min.js
View file

This file was deleted.

Loading

0 comments on commit b7bcc8f

Please sign in to comment.