Package Exports

react-medium-image-zoom
react-medium-image-zoom/dist/styles.css

Readme

react-medium-image-zoom

The original medium.com-style image zooming library for React.js.

Supports:

<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 />
Full accessibility:
- JAWS in Chrome, Edge, and Firefox (Windows)
- NVDA in Chrome, Edge, and Firefox (Windows)
- Safari + VoiceOver (macOS, iOS)

View the storybook examples to see various usages. NOTE: Help is wanted with making the examples more informative, so please start a discussion if you're able to help!

Installation

npm i react-medium-image-zoom

API

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

export interface UncontrolledProps {
  // Accessible label text for when you want to unzoom
  // Default: 'Minimize image'
  a11yNameButtonUnzoom?: string

  // Accessible label text for when you want to zoom
  // Default: 'Expand image'
  a11yNameButtonZoom?: string

  // Your image
  children: ReactNode

  // Provide your own unzoom button icon
  // Default: ICompress
  IconUnzoom?: ElementType

  // Provide your own zoom button icon
  // Default: IEnlarge
  IconZoom?: ElementType

  // Scrollable parent element
  // Default: window
  scrollableEl?: Window | HTMLElement

  // Higher quality image attributes to use on zoom
  zoomImg?: ImgHTMLAttributes<HTMLImageElement>

  // Offset in pixels the zoomed image should be from the `window`'s boundaries
  zoomMargin?: number
}

You can pass these options to only the Controlled component.

export interface ControlledProps {
  // ...same as UncontrolledProps

  // Tell the component whether or not it should be zoomed
  // Default: false
  isZoomed: boolean

  // Listen for hints from the component about when you
  // should zoom (`true` value) or unzoom (`false` value)
  onZoomChange?: (value: boolean) => void
}

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.

import React from 'react'
import Zoom from 'react-medium-image-zoom'
import 'react-medium-image-zoom/dist/styles.css'

// <img />
export const MyImg = () => (
  <Zoom>
    <img
      alt="That wanaka tree, alone in the water near mountains"
      src="/path/to/thatwanakatree.jpg"
      width="500"
    />
  </Zoom>
)

// <div>
export const MyDiv = () => (
  <Zoom>
    <div
      aria-label="That wanaka tree, alone in the water near mountains"
      role="img"
      style={{
        backgroundColor: '#fff',
        backgroundImage: `url("/path/to/thatwanakatree.jpg")`,
        backgroundPosition: '50%',
        backgroundRepeat: 'no-repeat',
        backgroundSize: 'cover',
        height: '0',
        paddingBottom: '56%',
        width: '100%',
      }}
    />
  </Zoom>
)

// <picture>
export const MyPicture = () => (
  <Zoom>
    <picture>
      <source media="(max-width: 800px)" srcSet="/path/to/teAraiPoint.jpg" />
      <img
        alt="A beautiful, serene setting in nature"
        src="/path/to/thatwanakatree.jpg"
        width="500"
      />
    </picture>
  </Zoom>
)

// <figure>
export const MyFigure = () => (
  <figure>
    <Zoom>
      <img
        alt="That wanaka tree, alone in the water near mountains"
        src="/path/to/thatwanakatree.jpg"
        width="500"
      />
    </Zoom>
    <figcaption>That Wanaka Tree</figcaption>
  </figure>
)

Controlled component

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

import React, { useCallback, useState } from 'react'
import { Controlled as ControlledZoom } from 'react-medium-image-zoom'
import 'react-medium-image-zoom/dist/styles.css'

const MyComponent = () => {
  const [isZoomed, setIsZoomed] = useState(false)

  const handleZoomChange = useCallback(shouldZoom => {
    setIsZoomed(shouldZoom)
  }, [])

  return (
    <ControlledZoom isZoomed={isZoomed} onZoomChange={handleZoomChange}>
      <img
        alt="That wanaka tree, alone in the water near mountains"
        src="/path/to/thatwanakatree.jpg"
        width="500"
      />
    </ControlledZoom>
  )
)

export 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.

Migrating From v4 to v5

TODO

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 💻	_{Sean King} 🤔	_{Ben Hood} 🤔 🐛 💡 👀	_Navilan 🤔	₁₃₈₀₆ 🐛	_{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 🤔

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