react-medium-image-zoom

This library is a React.js implementation of Medium.com's image zoom that allows for images to work together for a “zooming” effect and works regardless of parent elements that have overflow: hidden or parents with transform properties.

As an added bonus, it will let you zoom anything (see the Storybook Examples for more).

Blog post announcing v4

Links

• Installation
• Basic Usage
• API
• Migrating From v3 to v4
• Contributors
• Storybook Examples
• Changelog
• Contributing
• Code of Conduct

Installation

1npm i react-medium-image-zoom

or

1yarn add react-medium-image-zoom

or

1<!-- this build only needs React to be already present -->
2<script src="https://unpkg.com/react-medium-image-zoom"></script>

Basic Usage

Uncontrolled component (default)

Import the component and the CSS, wrap whatever you want to be "zoomable" with this component, and the component will handle it's own state:

1import React from 'react'
2import Zoom from 'react-medium-image-zoom'
3import 'react-medium-image-zoom/dist/styles.css'
4
5const MyComponent = () => (
6  <Zoom>
7    <img
8      alt="that wanaka tree"
9      src="/path/to/thatwanakatree.jpg"
10      width="500"
11    />
12  </Zoom>
13)
14
15export default MyComponent

You can zoom anything, so <picture>, <figure>, and even <div> elements are all valid:

1// <picture>
2<Zoom>
3  <picture>
4    <source media="(max-width: 800px)" srcSet="/path/to/teAraiPoint.jpg" />
5    <img
6      alt="that wanaka tree"
7      src="/path/to/thatwanakatree.jpg"
8      width="500"
9    />
10  </picture>
11</Zoom>
12
13// <figure>
14<figure>
15  <Zoom>
16    <img
17      alt="that wanaka tree"
18      src="/path/to/thatwanakatree.jpg"
19      width="500"
20    />
21  </Zoom>
22  <figcaption>That Wanaka Tree</figcaption>
23</figure>
24
25// <div> that looks like a circle
26<Zoom>
27  <div
28    aria-label="A blue circle"
29    style={{
30      width: 300,
31      height: 300,
32      borderRadius: '50%',
33      backgroundColor: '#0099ff'
34    }}
35  />
36</Zoom>

Controlled component (Controlled)

Import the Controlled component and the CSS, wrap whatever you want to be "zoomable" with this component and then dictate the zoomed/unzoomed state to the component. Here, we will automatically zoom the component once the image has loaded:

1import React, { useCallback, useState } from 'react'
2import { Controlled as ControlledZoom } from 'react-medium-image-zoom'
3import 'react-medium-image-zoom/dist/styles.css'
4
5const MyComponent = () => {
6  const [isZoomed, setIsZoomed] = useState(false)
7
8  const handleImgLoad = useCallback(() => {
9    setIsZoomed(true)
10  }, [])
11
12  const handleZoomChange = useCallback(shouldZoom => {
13    setIsZoomed(shouldZoom)
14  }, [])
15
16  return (
17    <ControlledZoom isZoomed={isZoomed} onZoomChange={handleZoomChange}>
18      <img
19        alt="that wanaka tree"
20        onLoad={handleImgLoad}
21        src="/path/to/thatwanakatree.jpg"
22        width="500"
23      />
24    </ControlledZoom>
25  )
26)
27
28export default MyComponent

The onZoomChange prop accepts a callback that will receive true or false based on events that occur (like click or scroll events) to assist you in determining when to zoom and unzoom the component.

There is also an example in the Storybook Examples of how to use a Controlled component to create a full-screen slideshow gallery.

API

Both uncontrolled & controlled components

You can pass these options to either the default or controlled components.

Prop	Type	Required	Default	Details
closeText	String	no	'Unzoom Image'	Accessible label text for when you want to unzoom
openText	String	no	'Zoom Image'	Accessible label text for when you want to zoom
overlayBgColorEnd	String	no	'rgba(255, 255, 255, 0.95)'	Modal overlay background color at end of zoom
overlayBgColorStart	String	no	'rgba(255, 255, 255, 0)'	Modal overlay background color at start of zoom
portalEl	Element	no	document.body	DOM Element to which we will append the zoom modal
scrollableEl	Window	no	window	DOM Element to which we will listen for scroll events to determine if we should unzoom
transitionDuration	Number	no	300	Transition duration in milliseconds for the component to use on zoom and unzoom. Set this to 0 to disable the animation
wrapElement	String	no	'div'	Wrapper element
wrapStyle	Object	no	null	Optional style object to pass to the wrapper element. Useful when you want the <Zoom> container to be width: '100%', for example
zoomMargin	Number	no	0	Offset in pixels the zoomed image should be from the window' boundaries
zoomZindex	Number	no	2147483647	z-index value for the zoom overlay

Only the controlled component

You can pass these options to only the controlled component.

Prop	Type	Required	Default	Details
isZoomed	bool	yes	false	Tell the component whether or not it should be zoomed
onZoomChange	Function	no	Function.prototype	Listen for hints from the component about when you should zoom (true value) or unzoom (false value)

Migrating From v3 to v4

In v3, you might have code like this:

1<ImageZoom
2  image={{
3    src: '/path/to/bridge.jpg',
4    alt: 'Golden Gate Bridge',
5    className: 'img',
6    style: { width: '50em' }
7  }}
8  zoomImage={{
9    src: '/path/to/bridge-big.jpg',
10    alt: 'Golden Gate Bridge'
11  }}
12  zoomMargin={80}
13/>

In v3, you would pass properties for your normal image that would be zoomed, and you would pass an optional zoomImage that would be a higher quality image that would replace the original image when zoomed.

The problem with v3 was that it tried to assume too many things about what it is you were trying to zoom, and this resulted in overly complex and near-unmaintainable code that had a number of bugs.

In v4, you can zoom the bridge example above like this:

1<Zoom zoomMargin={40}>
2  <img
3    src="/path/to/bridge.jpg"
4    alt="Golden Gate Bridge"
5    className="img"
6    style={{ width: '50em'}}
7  />
8</Zoom>

We've removed the zoomImage functionality (there is an issue for us to consider re-adding something like it), but as it was not a primary use case for many consumers, we opted to ship v4 without it.

Please see the Controlled component (Controlled) section for further documentation regarding controlled components that used the isZoomed, onZoom, and onUnzoom properties.

Contributors

Thanks goes to these wonderful people (emoji key):

Cameron Bothner 💻 📖 🐛 💡 🤔 👀 ⚠️	Jeremy Bini 💻 🐛	ismay 🐛 🤔	Rajit Singh 🐛	Roberto Saccon 🐛	wtfdaemon 🐛	Robert Pearce 💻 💬 ⚠️ 🐛 💡 🎨 👀 🤔 📖
Josh Sloat 🐛 💻 💡 👀 🤔 📖 🎨 💬	Aswin 💬	Alex Shelkovskiy 🐛	Adrian Bindiu 🐛	Kendall Buchanan 🐛	Kaycee 💻	Anuj 🐛 💬
Ludwig Frank 🐛 💻	LX 🐛 🤔	Rosen Tomov 🐛	Tom Moor 💻 🐛	Johan Preynat 💻 🐛	Rahul Gaba 💻 🐛	Spencer Davis 💻 🤔 👀 🎨
dnlnvl 💻	Sean King 🤔	Ben Hood 🤔 🐛 💡 👀	Navilan 🤔	13806 🐛	Akshay Kadam (A2K) 🐛 🤔	Jake Stewart 🐛 🤔
hhh 🐛	@davalapar 🐛	Sun Knudsen 💻 🐛 🤔 💡 💬 👀 ⚠️ 📖	Douglas Galdino 💻 📖 🐛 🤔 💡 👀 ⚠️	Mohammed Faragallah 🐛 🤔 💡	Youngrok Kim 💻 🐛	Nandhagopal Ezhilmaran 🐛
Mattia Astorino 🐛	Dan Wood 📖	Zachery C Gentry 🐛	xmflsct 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!