Zoomable Image

An interactive image wrapper that provides inline zooming and panning for detailed product inspection.

stylekeys: zoomableImage

ZoomableImage is only available in the React API for SWAN. This component requires internationalisation (i18n) to be set up in your application.

UsageGuidelinesAPI

Use Zoomable Image...

When the image contains visual details that matter for decisions and help customers feel confident about their choice or design. For example, checking product texture, small text, logo placement, or intricate artwork.
To allow users to examine image details in depth while keeping the surrounding page content visible.

Don’t use Zoomable Image...

For small images where detailed inspection provides little or no value.
Nested with other zoom or pan behaviors that may conflict with its interaction.
Avoid using ZoomableImage on purely decorative imagery, where zooming and panning do not add any real value to the experience.

<ZoomableImage src="/example-images/product.webp" alt="Cap with swan logo" />

<ZoomableImage src="/example-images/product.webp" alt="Cap with swan logo" />

With Callback

Use onExpandClick when clicking the image should open an extended view of that same image.
This is typically used to open a larger, more detailed view of the image for deeper inspection. For example, in a Lightbox that provides a second level of zoom, or in another focused container dedicated to viewing the image at a larger size, with any supporting details or actions.

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  return (
    <>
      <Box style={{ width: '400px' }}>
        <ZoomableImage
          src="/example-images/1x1-6.webp"
          onExpandClick={() => setIsOpen(true)}
        />
      </Box>
      <Lightbox isOpen={isOpen} onRequestDismiss={() => setIsOpen(false)}>
        <ZoomableImage src="/example-images/1x1-6.webp" />
      </Lightbox>
    </>
  )
}

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  return (
    <>
      <Box style={{ width: '400px' }}>
        <ZoomableImage
          src="/example-images/1x1-6.webp"
          onExpandClick={() => setIsOpen(true)}
        />
      </Box>
      <Lightbox isOpen={isOpen} onRequestDismiss={() => setIsOpen(false)}>
        <ZoomableImage src="/example-images/1x1-6.webp" />
      </Lightbox>
    </>
  )
}

With Adaptive carousel

Use ZoomableImage inside an Adaptive carousel to provide zoom and pan interactions for the carousel image slides.

<AdaptiveCarousel aria-label="Carousel" slidesToShow={3}>
  <AdaptiveCarouselSlide>
    <ZoomableImage src="/example-images/product.webp" />
  </AdaptiveCarouselSlide>
  <AdaptiveCarouselSlide>
    <ZoomableImage src="/example-images/product-2.webp" />
  </AdaptiveCarouselSlide>
  <AdaptiveCarouselSlide>
    <ZoomableImage src="/example-images/product-3.webp" />
  </AdaptiveCarouselSlide>
  <AdaptiveCarouselSlide>
    <ZoomableImage src="/example-images/product-4.webp" />
  </AdaptiveCarouselSlide>
  <AdaptiveCarouselSlide>
    <ZoomableImage src="/example-images/product-5.webp" />
  </AdaptiveCarouselSlide>
</AdaptiveCarousel>

<AdaptiveCarousel aria-label="Carousel" slidesToShow={3}>
  <AdaptiveCarouselSlide>
    <ZoomableImage src="/example-images/product.webp" />
  </AdaptiveCarouselSlide>
  <AdaptiveCarouselSlide>
    <ZoomableImage src="/example-images/product-2.webp" />
  </AdaptiveCarouselSlide>
  <AdaptiveCarouselSlide>
    <ZoomableImage src="/example-images/product-3.webp" />
  </AdaptiveCarouselSlide>
  <AdaptiveCarouselSlide>
    <ZoomableImage src="/example-images/product-4.webp" />
  </AdaptiveCarouselSlide>
  <AdaptiveCarouselSlide>
    <ZoomableImage src="/example-images/product-5.webp" />
  </AdaptiveCarouselSlide>
</AdaptiveCarousel>

With Overlay Element

<FlexBox style={{ position: 'relative', width: 'fit-content' }}>
  <Box
    pt={5}
    pr={5}
    style={{
      position: 'absolute',
      right: '0px',
      zIndex: 'var(--swan-sem-z-index-raised)',
    }}
  >
    <Checkbox skin="favorite" aria-label="Add to favorites" />
  </Box>
  <ZoomableImage src="/example-images/product.webp" />
</FlexBox>

<FlexBox style={{ position: 'relative', width: 'fit-content' }}>
  <Box
    pt={5}
    pr={5}
    style={{
      position: 'absolute',
      right: '0px',
      zIndex: 'var(--swan-sem-z-index-raised)',
    }}
  >
    <Checkbox skin="favorite" aria-label="Add to favorites" />
  </Box>
  <ZoomableImage src="/example-images/product.webp" />
</FlexBox>

Control

When ZoomableImage is used directly on the page (outside a Lightbox), it provides an inline zoom experience. Hovering the image with a pointer, or pressing the assigned (+ / -) zoom keys when it has keyboard focus, triggers zoom.
When ZoomableImage is used inside a Lightbox, clicking the image (with a pointer or via keyboard activation) toggles zoom on and off.
Once zoomed (inline or in a Lightbox), moving the pointer or using the arrow keys pans within the zoomed image.
On touch devices, users rely on the browser’s native pinch‑to‑zoom and pan, so there’s no additional UI control to enable and no extra implementation required.

Minimum size

Avoid using ZoomableImage at widths under 320px. Inspection becomes restricted and sub‑optimal in containers smaller than this threshold. Instead, use a Lightbox, rather than relying on inline zoom.

Props

ZoomableImage

This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag.

See core props for additional props that can be applied to this component.

prop	type	required	description	default
onLoad	`(ReactEventHandler<HTMLDivElement> & ReactEventHandler<HTMLImageElement>)`	false	Callback triggered when the image successfully loads	null
onError	`(ReactEventHandler<HTMLDivElement> & ReactEventHandler<HTMLImageElement>)`	false	Callback triggered when the image fails to load	null
src	`string \| undefined`	true	Source URL for the image	null
srcSet	`string`	false	Image sources for different viewport sizes and pixel densities	null
sizes	`string`	false	Media query conditions for the srcSet attribute	null
alt	`string`	false	Accessible label describing the image content	null
onExpandClick	`(() => void)`	false	Callback triggered when the image is clicked, to expand/open a larger or more detailed view	null

Internationalization

SWAN's Internationalization System allows SWAN components to render with fully translated and accessible text out-of-the-box. The following keys are provided to allow you to override the default translation.

Default Text	Key
Zoomable Image	`zoomable-image.accessible-label`
Click to expand	`zoomable-image.accessible-label-hover-trigger-button`
Click to zoom in and zoom out	`zoomable-image.accessible-label-click-trigger-button`
Zoomed to {{zoomLevel}}	`zoomable-image.zoom-to-label`
maximum	`zoomable-image.zoom-level-max`
minimum	`zoomable-image.zoom-level-min`
Click to zoom in or zoom out and use arrow keys to pan	`zoomable-image.click-instruction`
Use {{zoomInKey}} and {{zoomOutKey}} key to zoom and arrow keys to pan	`zoomable-image.hover-instruction`
Use plus and minus key to zoom and arrow keys to pan Accessible instructions for keyboard users on how to interact with the component	`zoomable-image.accessible-text-for-hover-instruction`
Use arrow keys to pan Accessible instructions for keyboard users on how to interact with the component	`zoomable-image.accessible-text-for-click-instruction`