react-inner-image-zoom
Version:
A React component for magnifying an image within its parent container 🔎
106 lines (72 loc) • 5.72 kB
Markdown
[![GitHub Actions][build-badge]][build] [![NPM][npm-badge]][npm]
A lightweight React component for magnifying an image within its original container.
[](https://innerimagezoom.com/) | [Changelog](https://github.com/laurenashpole/inner-image-zoom/blob/main/packages/react/CHANGELOG.md)
**Note:** Version 2.0.0 introduces React hooks and requires React v16.8.0 or above. To use this package with older versions of React, install with `npm install react-inner-image-zoom@1.3.0` or `yarn add react-inner-image-zoom@1.3.0` instead of the instructions below.
```
npm install react-inner-image-zoom
```
```
yarn add react-inner-image-zoom
```
[](https://github.com/laurenashpole/inner-image-zoom/blob/main/packages/react/src/index.d.ts) were added with version 4.0.0. For older installations, type definitions are available through [DefinitelyTyped](https://definitelytyped.org/) and can be installed with:
```
npm install --save-dev @types/react-inner-image-zoom
```
You can download the raw [styles.css](https://raw.githubusercontent.com/laurenashpole/inner-image-zoom/main/packages/react/src/styles.css) file or, if your build supports it, import the stylesheet directly from node_modules using:
```javascript
import 'react-inner-image-zoom/lib/styles.min.css';
```
Import and render the component:
```javascript
import InnerImageZoom from 'react-inner-image-zoom';
...
<InnerImageZoom src="/path/to/image.jpg" zoomSrc="/path/to/zoom-image.jpg" />
```
This is the simplest usage. For additional examples, visit the [demo page](https://innerimagezoom.com/).
Prop | Type | Default | Description
--- | --- | --- | ---
src | string | | **(Required)** URL for the original image.
sources | array | | A list of image sources for using the picture tag to serve the appropriate original image (see below for more details).
width | number | | Width attribute for original image.
height | number | | Height attribute for original image.
hasSpacer | boolean | false | If true, gets the original image's aspect ratio based on the width and height props and creates a spacer to prevent cumulative layout shift.
imgAttributes | object | | [Img](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attributes) and [global](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes) attributes for the original image (excluding `src`, `width`, `height`, and `style` which are set elsewhere). The imgAttributes keys should follow the [React DOM element](https://reactjs.org/docs/dom-elements.html) naming conventions.
zoomSrc | string | | URL for the larger zoom image. Falls back to original image src if not defined.
zoomScale | number | 1 | Multiplied against the natural width and height of the zoomed image. This will generally be a decimal (example, 0.9 for 90%).
zoomPreload | boolean | false | If set to true, preloads the zoom image instead of waiting for mouseenter and (unless on a touch device) persists the image on mouseleave.
moveType | `pan` or `drag` | pan | The user behavior for moving zoomed images on non-touch devices.
zoomType | `click` or `hover` | click | The user behavior for triggering zoom. When using `hover`, combine with `zoomPreload` to avoid flickering on rapid mouse movements.
fadeDuration | number | 150 | Fade transition time in milliseconds. If zooming in on transparent images, set this to `0` for best results.
fullscreenOnMobile | boolean | false | Enables fullscreen zoomed image on touch devices below a specified breakpoint.
mobileBreakpoint | number | 640 | The maximum breakpoint for fullscreen zoom image when fullscreenOnMobile is true.
hideCloseButton | boolean | false | Hides the close button on touch devices. If set to true, zoom out is triggered by tap.
hideHint | boolean | false | Hides the magnifying glass hint.
className | string | | Custom classname for styling the component.
afterZoomIn | () => void | | Function to be called after zoom in.
afterZoomOut | () => void | | Function to be called after zoom out.
The `ref` prop forwards an object with the `container` (the root `figure` element) and `portal` DOM nodes. `portal` grants access to the zoomed image on touch devices when `fullscreenOnMobile` is set and is only available while the image is zoomed. When using with TypeScript, `InnerImageZoomRef` can be imported to use as a type argument with `useRef`.
This prop accepts an array of objects which it uses to create a picture tag and source elements. The component looks for the following optional properties and you can find additional details on responsive images [here](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images):
Prop | Type | Default | Description
--- | --- | --- | ---
srcSet | string | | Srcset attribute for source tag.
sizes | string | | Sizes attribute for source tag.
media | string | | An attribute containing a media condition for use with the srcset.
type | string | | An image MIME type. This is useful for using newer formats like WebP.
Please submit bugs or requests on the [GitHub issues page](https://github.com/laurenashpole/inner-image-zoom/issues) and make sure to use the `react` label.
[](https://github.com/laurenashpole/inner-image-zoom/blob/main/LICENSE)
[]: http://img.shields.io/npm/v/react-inner-image-zoom.svg?style=flat
[]: https://www.npmjs.com/package/react-inner-image-zoom
[]: https://github.com/laurenashpole/inner-image-zoom/actions/workflows/release.yml/badge.svg
[]: https://github.com/laurenashpole/inner-image-zoom/actions