Skip to content

rpearce/react-medium-image-zoom

main
Switch branches/tags
Code

Files

Permalink
Failed to load latest commit information.

react-medium-image-zoom

npm version bundlephobia size npm downloads All Contributors

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

Features:

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!

Quickstart

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

export const MyImg = () => (
  <Zoom>
    <img
      alt="That Wanaka Tree, New Zealand by Laura Smetsers"
      src="/path/to/thatwanakatree.jpg"
      width="500"
    />
  </Zoom>
)

This library's compilation target is ES2022, but it only uses features from ES2020 and below. If you find you need to support older browsers, add react-medium-image-zoom to your build system.

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
  // Default: 0
  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, New Zealand by Laura Smetsers"
      src="/path/to/thatwanakatree.jpg"
      width="500"
    />
  </Zoom>
)

// <div>
export const MyDiv = () => (
  <Zoom>
    <div
      aria-label="That Wanaka Tree, New Zealand by Laura Smetsers"
      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, New Zealand by Laura Smetsers"
        src="/path/to/thatwanakatree.jpg"
        width="500"
      />
    </Zoom>
    <figcaption>Photo by Laura Smetsers</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.

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

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
  • 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

πŸ“– πŸ›

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