react-medium-image-zoom

The original medium.com-inspired image zooming library for React.

View the storybook examples to see various usages.

Features:

• <img />, including all object-fit values, any object-position, and loading="lazy"
• <div> and <span> with any background-image, background-size, and background-position
• <picture> with <source /> and <img />
• <figure> with <img />
• <svg>
• Custom zoom modal content (👇)
• Accessibility:
  • JAWS in Chrome, Edge, and Firefox (Windows)
  • NVDA in Chrome, Edge, and Firefox (Windows)
  • VoiceOver in Safari (macOS, iOS)
  • TalkBack in Chrome (Android)
• Supports popular tools:
  • Gatsby and gatsby-plugin-image
  • Next.js
• Zero dependencies

Requirements to know about:

• <dialog> element (caniuse dialog)
• ResizeObserver (caniuse ResizeObserver)
• Package build target is ES2021. If you need to support older environments, run this package through your build system.

Media and Tutorials

• 2024-08-2024 — React Round Up — "Building a Seamless Image Zoom Feature"
• Build a React.js Image Zoom Feature with react-medium-image-zoom Library and State Management

Quickstart

1npm install --save react-medium-image-zoom

1import React from 'react'
2import Zoom from 'react-medium-image-zoom'
3import 'react-medium-image-zoom/dist/styles.css'
4
5export const MyImg = () => (
6  <Zoom>
7    <img
8      alt="That Wanaka Tree, New Zealand by Laura Smetsers"
9      src="/path/to/thatwanakatree.jpg"
10      width="500"
11    />
12  </Zoom>
13)

API

You can pass these options to either the Uncontrolled (default) or Controlled components.

1export interface UncontrolledProps {
2  // Accessible label text for when you want to unzoom.
3  // Default: 'Minimize image'
4  a11yNameButtonUnzoom?: string
5
6  // Accessible label text for when you want to zoom.
7  // Default: 'Expand image'
8  a11yNameButtonZoom?: string
9
10  // Allow swipe gesture to unzoom.
11  // Default: true
12  canSwipeToUnzoom?: boolean
13
14  // Your image (required).
15  children: ReactNode
16
17  // Custom CSS className to add to the zoomed <dialog>.
18  classDialog?: string
19
20  // Provide your own unzoom button icon.
21  // Default: ICompress
22  IconUnzoom?: ElementType
23
24  // Provide your own zoom button icon.
25  // Default: IEnlarge
26  IconZoom?: ElementType
27
28  // Disables the zoom/unzoom behavior.
29  // Default: false
30  isDisabled?: boolean
31
32  // Swipe gesture threshold after which to unzoom.
33  // Default: 10
34  swipeToUnzoomThreshold?: number
35
36  // Specify what type of element should be used for
37  // internal component usage. This is useful if the
38  // image is inside a <p> or <button>, for example.
39  // Default: 'div'
40  wrapElement?: 'div' | 'span'
41
42  // Provide your own custom modal content component.
43  ZoomContent?: (props: {
44    img: ReactElement | null;
45    buttonUnzoom: ReactElement<HTMLButtonElement>;
46    onUnzoom: () => void;
47  }) => ReactElement;
48
49  // Higher quality image attributes to use on zoom.
50  zoomImg?: ImgHTMLAttributes<HTMLImageElement>
51
52  // Offset in pixels the zoomed image should
53  // be from the window's boundaries.
54  // Default: 0
55  zoomMargin?: number
56}

You can pass these options to only the Controlled component.

1export interface ControlledProps {
2  // ...same as UncontrolledProps
3
4  // Tell the component whether or not it should be zoomed
5  // Default: false
6  isZoomed: boolean
7
8  // Listen for hints from the component about when you
9  // should zoom (`true` value) or unzoom (`false` value)
10  onZoomChange?: (value: boolean) => void
11}

Basic Usage

Uncontrolled component (default)

Import the component and the CSS, wrap your image with the 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
5// <img />
6export const MyImg = () => (
7  <Zoom>
8    <img
9      alt="That Wanaka Tree, New Zealand by Laura Smetsers"
10      src="/path/to/thatwanakatree.jpg"
11      width="500"
12    />
13  </Zoom>
14)
15
16// <div>
17export const MyDiv = () => (
18  <Zoom>
19    <div
20      aria-label="That Wanaka Tree, New Zealand by Laura Smetsers"
21      role="img"
22      style={{
23        backgroundColor: '#fff',
24        backgroundImage: `url("/path/to/thatwanakatree.jpg")`,
25        backgroundPosition: '50%',
26        backgroundRepeat: 'no-repeat',
27        backgroundSize: 'cover',
28        height: '0',
29        paddingBottom: '56%',
30        width: '100%',
31      }}
32    />
33  </Zoom>
34)
35
36// <picture>
37export const MyPicture = () => (
38  <Zoom>
39    <picture>
40      <source media="(max-width: 800px)" srcSet="/path/to/teAraiPoint.jpg" />
41      <img
42        alt="A beautiful, serene setting in nature"
43        src="/path/to/thatwanakatree.jpg"
44        width="500"
45      />
46    </picture>
47  </Zoom>
48)
49
50// <figure>
51export const MyFigure = () => (
52  <figure>
53    <Zoom>
54      <img
55        alt="That Wanaka Tree, New Zealand by Laura Smetsers"
56        src="/path/to/thatwanakatree.jpg"
57        width="500"
58      />
59    </Zoom>
60    <figcaption>Photo by Laura Smetsers</figcaption>
61  </figure>
62)

Controlled component

Import the Controlled component and the CSS, wrap your image with the component, and then dictate the isZoomed state to the component.

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 handleZoomChange = useCallback(shouldZoom => {
9    setIsZoomed(shouldZoom)
10  }, [])
11
12  return (
13    <ControlledZoom isZoomed={isZoomed} onZoomChange={handleZoomChange}>
14      <img
15        alt="That wanaka tree, alone in the water near mountains"
16        src="/path/to/thatwanakatree.jpg"
17        width="500"
18      />
19    </ControlledZoom>
20  )
21}
22
23export 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.

Styles

You can import the default styles from react-medium-image-zoom/dist/styles.css and override the values from your code, or you can copy the styles.css file and alter it to your liking. The latter is the best option, given rems should be used instead of px to account for different default browser font sizes, and it's hard for a library to guess at what these values should be.

An example of customizing the transition duration, timing function, overlay background color, and unzoom button styles with :focus-visible can be found in this story: https://rpearce.github.io/react-medium-image-zoom/?path=/story/img--custom-modal-styles

Custom zoom modal content

If you want to customize the zoomed modal experience with a caption, form, or other set of components, you can do so by providing a custom component to the ZoomContent prop.

View the live example of custom zoom modal content.

Below is some example code that demonstrates how to use this feature.

1export const MyImg = () => (
2  <Zoom ZoomContent={CustomZoomContent}>
3    <img
4      alt="That Wanaka Tree, New Zealand by Laura Smetsers"
5      src="/path/to/thatwanakatree.jpg"
6      width="500"
7    />
8  </Zoom>
9)
10
11const CustomZoomContent = ({
12  /** Default unzoom button */
13  buttonUnzoom,
14
15  /** Current state of the zoom modal: UNLOADED, LOADING, LOADED, UNLOADING */
16  modalState,
17
18  /** Your image, prepped for zooming */
19  img,
20
21  /** A state to check if the zoom img is loaded (useful for loading state) */
22  // isZoomImgLoaded,
23
24  /**
25   * A callback to manually unzoom the image and close the modal if you want to
26   * use your own buttons or listeners in your custom experience.
27   */
28  //onUnzoom,
29}) => {
30  const [isLoaded, setIsLoaded] = useState(false)
31
32  useLayoutEffect(() => {
33    if (modalState === 'LOADED') {
34      setIsLoaded(true)
35    } else if (modalState === 'UNLOADING') {
36      setIsLoaded(false)
37    }
38  }, [modalState])
39
40  const classCaption = isLoaded
41    ? 'zoom-caption zoom-caption--loaded'
42    : 'zoom-caption'
43
44  return <>
45    {buttonUnzoom}
46
47    <figure>
48      {img}
49      <figcaption className={classCaption}>
50        That Wanaka Tree, also known as the Wanaka Willow, is a willow tree
51        located at the southern end of Lake Wānaka in the Otago region of New
52        Zealand.
53        <cite className="zoom-caption-cite">
54          Wikipedia, <a className="zoom-caption-link" href="https://en.wikipedia.org/wiki/That_Wanaka_Tree">
55            That Wanaka Tree
56          </a>
57        </cite>
58      </figcaption>
59    </figure>
60  </>
61}

Migrating From v4 to v5

Here are the prop changes from v4 to be aware of:

• closeText was renamed to a11yNameButtonUnzoom
• openText was renamed to a11yNameButtonZoom
• overlayBgColorStart was removed and is now controlled via the CSS selector [data-rmiz-modal-overlay="hidden"]
• overlayBgColorEnd was removed and is now controlled via the CSS selector [data-rmiz-modal-overlay="visible"]
• portalEl was removed, for we are using the <dialog> element now
• transitionDuration was removed and is now controlled via the CSS selectors [data-rmiz-modal-overlay] and [data-rmiz-modal-img]
• wrapElement was removed then added back in v5.1.0
• wrapStyle was removed
• zoomZindex was removed, for we are using the <dialog> element now

And you can now provide zoomImg props to specify a different image to load when zooming.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Robert Pearce 💻 💬 ⚠️ 🐛 💡 🎨 👀 🤔 📖	Cameron Bothner 💻 📖 🐛 💡 🤔 👀 ⚠️	Jeremy Bini 💻 🐛	ismay 🐛 🤔	Rajit Singh 🐛	Roberto Saccon 🐛	wtfdaemon 🐛
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 💻	Madi 🤔	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 🐛	Will.iam 💻 ⚠️	Gourav Goyal 📖	Joshua Chen 🐛 💻
David Edler 🐛 💻	rikusen0335 🤔	Surjith S M 🤔	developergunny 🐛	Khan Mohsin 💬	Robin Goudeketting 🐛	Botros Toro 🤔
Christian Guevara 💬	Johan Book 🐛	Paolo Di Bello 🤔	Tommaso De Rossi 📖 🐛	Lezan 🐛 🤔	Ibrahim H. Sluma 🐛	Ben Gotow 🐛
Rubon72 🐛	wanderingme 🐛	Thomas Strobl 🐛 🤔 💡 💬 👀	Songkeys 🐛 🤔 💡 💬 👀	AntoineS92 🐛	Sindre Aubert 🐛	mx 🐛
Sander Heling 🐛	Yida Zhang 🐛 💻	Nir 🐛	hhatakeyama 🐛	Paco 🐛 🤔	LichLord91 🐛	just-small-potato 🤔
walmsles 🐛	tenshin 💬	Steven Tey 🐛	Sergey 🐛 💻 📖	Diego Azevedo 📖	Faizan Ahmad 🐛	Kunal L. 🐛
Kevin Wang 🤔	u3u 🤔 👀	Hong 💻	Wojciech Rok 💻 🤔	Matija 🐛	Jiayi Hu 🐛	Zeit der Forschung 🐛
Andrei Barabas 🐛 🤔	Németh Benedek 🐛	iMalFect 🐛	Karl Horky 🐛 🤔 👀	陈杨文 🐛	Zohaib Khan 💻

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