Docs

Everything <ImageZoom> can do, with live examples. Every image on this page opens.

Usage

Package manager
npm install astro-image-zoom@beta
pnpm add astro-image-zoom@beta
yarn add astro-image-zoom@beta
bun add astro-image-zoom@beta

Put <ImageZoom> around any markup with images. It wraps each one in a link to the file the zoom opens, so without JavaScript the link still opens the image.

---
import ImageZoom from 'astro-image-zoom/ImageZoom.astro';
---
<ImageZoom>
  <img src="/earthrise.jpg" alt="Earth rising above the Moon" />
</ImageZoom>

A larger file for the zoom. The zoom never shows an image bigger than its file, and without data-image-zoom-src it opens the image's own src. When the page shows a smaller version, such as a thumbnail in an <img> or the 800 px file Astro's <Image width={800}> generates, point data-image-zoom-src at the full-size one.

---
import ImageZoom from 'astro-image-zoom/ImageZoom.astro';
import { Image, getImage } from 'astro:assets';
import photo from '../assets/earthrise.jpg';

// Full-size version for the zoom
const fullSize = await getImage({ src: photo, width: photo.width });
---
<ImageZoom>
  <Image src={photo} alt="Earth rising above the Moon" width={800}
    data-image-zoom-src={fullSize.src} data-image-zoom-caption="Earthrise — Apollo 8, 1968" />
</ImageZoom>

Image sources

Astro's <Image> and <Picture>, a plain <img>from public/, or an image on another server.

Prefer <Image> or <Picture>: Astro resizes and compresses them, so the page loads light images; with data-image-zoom-src, the zoom fetches the full size only when it opens. Plain<img> tags work just as well, but they ship whatever file you give them.

Pillars of Creation: towering columns of gas and dust in the Eagle Nebula, in near-infrared light

<Image> · Pillars of Creation

Sunflower galaxy Messier 63, with dusty spiral arms around a bright core

<Picture> · Sunflower galaxy

The whole Earth, with Africa and Antarctica under swirling white clouds

<img> from public/ · The Blue Marble

Pillar of gas and dust in the Carina Nebula, photographed by Hubble

Remote <img> · Mystic Mountain

Show code
<ImageZoom>
  <Image src={photo} alt="…" width={640} data-image-zoom-src={fullSize.src} />
  <Picture src={photo} alt="…" widths={[640]} formats={['avif', 'webp']} data-image-zoom-src={fullSize.src} />
  <img src="/images/blue-marble-small.jpg" alt="…" data-image-zoom-src="/images/blue-marble.jpg" />
  <img src="https://images-assets.nasa.gov/image/PIA15985/PIA15985~large.jpg" alt="…" />
</ImageZoom>

An image inside a link with data-image-zoom opens the link's href. Put the caption on the link, in data-image-zoom-caption or title: the image inside only gives its alt text. Images inside any other link, or inside a button, are left alone, so cards and logos keep working as links.

<ImageZoom>
  <a href="/full-size-1.jpg" data-image-zoom data-image-zoom-caption="Harbor at dawn">
    <img src="/thumbnail-1.jpg" alt="Harbor at dawn" />
  </a>
</ImageZoom>

Nested markup

Images at any depth inside the component zoom too, like those of this card.

Crawler carrying the Apollo 11 Saturn V and its tower along the road to the launch pad

Photo essay · 4 images

Leaving the pad

From Mercury capsules to the Space Shuttle: how the early crews got to space and back.

John Glenn in his spacesuit inside the Friendship 7 capsule, filmed by an onboard camera
Alan Shepard lifted by a helicopter from the ocean after his flight
Space shuttle Challenger rising on a column of smoke over the Florida coast, seen from above

Framework components (React, Vue, Svelte…) render on the server too, so their images zoom. Hydrated islands (client:*) are the exception: the zoom leaves the images they render alone, so it never breaks their hydration. The Astro children you pass to an island zoom as usual, and an island can render its own <a data-image-zoom> link: see how.

Leaving images out

Logos, avatars and decorative images inside a wrapped article shouldn't zoom. List them in the ignore prop: an ignored image isn't wrapped in a link and doesn't count in the gallery. Each selector is checked against the image and every element around it, so .author leaves out every image in the aside.

Show code
<ImageZoom ignore=".logo, .author, [alt='']">
  <img src="/photo.jpg" alt="Harbor at dawn" />
  <img class="logo" src="/logo.svg" alt="Harbor Co." />
  <img src="/divider.svg" alt="" />
  <aside class="author"><img src="/avatar.jpg" alt="The author" /></aside>
  <!-- One image, without the prop -->
  <img src="/signature.svg" alt="Signature" data-image-zoom-ignore />
</ImageZoom>

The images are wrapped on the server, without a DOM, soignore takes simple selectors only: a tag name,.classes, #ids and[attributes], combined as inimg.logo[alt='']. Spaces inside a selector, combinators and pseudo-classes fail the build with an error that names the selector.

Your thumbnails

The component doesn't style the images on your page, not even their focus ring. Each one gets an inline<a data-image-zoom-generated> with your link styles, and if your images are display: block, the outline of that link doesn't wrap them. Draw your focus ring on the image instead, as this page does.

a[data-image-zoom-generated]:focus-visible {
  outline: none;
}

a[data-image-zoom-generated]:focus-visible img {
  outline: 2px solid green; /* your focus ring */
  outline-offset: 3px; /* negative if a parent with overflow: hidden clips it */
}

Starlight

In a Starlight site, one line in the config makes every image of the docs zoomable, with no component in the pages. Each page is one gallery, and a Markdown image's title becomes its caption: ![A red car](./car.jpg "Our first car").

// astro.config.mjs
import starlight from '@astrojs/starlight';
import imageZoom from 'astro-image-zoom/starlight';
import { defineConfig } from 'astro/config';

export default defineConfig({
  integrations: [starlight({ title: 'My docs', plugins: [imageZoom()] })],
});

The options are the props of <ImageZoom>, except labels and class. The zoom takes Starlight's colors and follows its theme toggle; your CSS variables and the theme option replace those colors.

imageZoom({ showCounter: false, theme: { backgroundColor: 'black' } });

The labels come from Starlight's UI translations, in English and Spanish, in the language of each page. For another language, add the keys to src/content/i18n/<lang>.json; any label left out stays in English.

Show code
{
  "astroImageZoom.overlay": "Zoom d'image",
  "astroImageZoom.close": "Fermer le zoom",
  "astroImageZoom.images": "Images",
  "astroImageZoom.previous": "Image précédente",
  "astroImageZoom.next": "Image suivante",
  "astroImageZoom.enlarge": "Agrandir l'image",
  "astroImageZoom.enlargeNamed": "Agrandir l'image : {alt}"
}

If your site already overrides Starlight's MarkdownContent, the plugin leaves yours, and you wrap it in the zoom yourself.

Behavior

Props change how the zoom moves and closes. Open each example to try it.

  • Orion spacecraft with the NASA logo, with Earth and Moon small in the black distance
    Orion's solar array between Earth and the Moon, seen from a camera on its tip
    Grey cratered surface of the Moon filling the view beside the Orion spacecraft

    No arrows or counter

    Keys and swipes still move through the gallery.

    <ImageZoom showNavigation={false}>
  • Ed White floating on a tether above Earth during the first American spacewalk

    Stays open on a backdrop click

    A click on the backdrop does nothing; the close button and Escape still work.

    <ImageZoom closeOnBackdrop={false}>
  • Bruce McCandless flying untethered with a jetpack above Earth

    Stays open on an image click

    A click on the zoomed image does nothing.

    <ImageZoom closeOnImage={false}>
  • Astronaut Randy Bresnik dwarfed by the space station's huge solar arrays, with Earth behind

    Stays open while scrolling

    A wheel, a touchpad scroll or a vertical swipe doesn't close it.

    <ImageZoom closeOnScroll={false}>

Animation

The image grows from its thumbnail and shrinks back into it, or fades in where it lands. Its length, its curves and the way each caption comes in are props and CSS variables, so each gallery can have a feel of its own. With reduced motion nothing animates, whatever is set here.

  • Apollo 11 Saturn V rocket clearing the launch tower in a burst of fire
    Andromeda galaxy in ultraviolet light, with blue spiral arms around a golden core

    Faster or slower

    The length of the zoom in milliseconds: 150 on the left, 800 on the right.

    <ImageZoom animationDuration={150}>
    <ImageZoom animationDuration={800}>
  • A blue and white Earth setting behind the grey, cratered horizon of the Moon
    A small white Sun setting behind dark hills on Mars, in a hazy sky that glows blue around it

    Zoom or fade

    The image grows from its thumbnail on the left, and fades in where it lands on the right: calmer, and the thumbnail stays on the page.

    <ImageZoom>
    <ImageZoom animation="fade">
  • The Gemini 7 spacecraft, small and white against black space, above the curve of the Earth, seen from the window of Gemini 6
    The nose of the Gemini 7 spacecraft facing the camera, the words United States on its side, against black space
    The Gemini 7 spacecraft seen from behind, its gold heat shield toward the camera, above the blue Earth and its clouds

    Captions in parallax

    Move through the gallery: each new caption comes in from the side of its image, a shorter way than the photos, so it floats above them. By default it only fades in.

    .gallery {
      --image-zoom-caption-enter-x: 120px;
    }
  • Faint spiral galaxy NGC 3274, a bluish haze of stars against dark space

    A caption that rises

    The caption rises into place as the photo opens, and with each new image of a gallery. At the top, it comes down.

    .gallery {
      --image-zoom-caption-enter-y: 24px;
    }

Easing

--image-zoom-easing-in sets the curve of the opening and --image-zoom-easing-out the curve of the closing. Any CSS easing works: cubic-bezier(), steps() and linear() springs and bounces. Each graph shows the opening, time across and size up. Open the photos to compare them, or mix your own in the playground.

  • A white SpaceX Dragon capsule, nose first, approaching over a sea of clouds with the thin blue edge of Earth above

    Snappy

    Leaves fast and settles slowly, like the motion of Material 3.

    .snappy {
      --image-zoom-animation-duration: 400ms;
      --image-zoom-easing-in: cubic-bezier(0.05, 0.7, 0.1, 1);
      --image-zoom-easing-out: cubic-bezier(0.3, 0, 0.8, 0.15);
    }
  • Young star cluster glittering in red and blue above clouds of glowing gas and dust in shades of blue, cream and brown

    Back

    Grows past the screen and comes back; on the way out, it winds up before it shrinks.

    .back {
      --image-zoom-animation-duration: 600ms;
      --image-zoom-easing-in: cubic-bezier(0.34, 1.56, 0.64, 1);
      --image-zoom-easing-out: cubic-bezier(0.36, 0, 0.66, -0.56);
    }
  • The Sun in teal ultraviolet light, its surface mottled with loops, with a bright white flare bursting on its left edge

    Spring

    Wobbles into place, with a linear() curve.

    .spring {
      --image-zoom-animation-duration: 900ms;
      --image-zoom-easing-in: linear(0, 0.009, 0.035 2.1%, 0.141, 0.281 6.7%, 0.723 12.9%, 0.938 16.7%, 1.017, 1.077, 1.121, 1.149 24.3%, 1.159, 1.163, 1.161, 1.154 29.9%, 1.129 32.8%, 1.051 39.6%, 1.017 43.1%, 0.991, 0.977 51%, 0.974 53.8%, 0.975 57.1%, 0.997 69.8%, 1.003 76.9%, 1.004 83.8%, 1);
    }
  • Astronaut John Young in mid-air on the Moon, saluting the flag beside the lunar module

    Bounce

    Lands like a ball, on the screen and back on the thumbnail. Never past either.

    .bounce {
      --image-zoom-animation-duration: 1000ms;
      --image-zoom-easing-in: linear(0, 0.01, 0.04, 0.09, 0.16, 0.25, 0.36, 0.49, 0.64, 0.81, 1 36.4%, 0.891, 0.813, 0.766, 0.75 54.5%, 0.766, 0.813, 0.891, 1 72.7%, 0.953, 0.938 81.8%, 0.953, 1 90.9%, 0.988, 0.984 95.5%, 0.988, 1);
      --image-zoom-easing-out: linear(0, 0.01, 0.04, 0.09, 0.16, 0.25, 0.36, 0.49, 0.64, 0.81, 1 36.4%, 0.891, 0.813, 0.766, 0.75 54.5%, 0.766, 0.813, 0.891, 1 72.7%, 0.953, 0.938 81.8%, 0.953, 1 90.9%, 0.988, 0.984 95.5%, 0.988, 1);
    }
  • The edge of the Moon filling the left of the frame, with a thin crescent Earth far off in the black sky

    Cinematic

    A long, slow glide that eases all the way in.

    .cinematic {
      --image-zoom-animation-duration: 1200ms;
      --image-zoom-easing-in: cubic-bezier(0.16, 1, 0.3, 1);
      --image-zoom-easing-out: cubic-bezier(0.7, 0, 0.84, 0);
    }
  • The SLS rocket rising at night on a column of white fire above billowing clouds of smoke, beside the launch towers

    Stop motion

    Six frames and no tweening, like a flip book.

    .stop-motion {
      --image-zoom-animation-duration: 700ms;
      --image-zoom-easing-in: steps(6, jump-none);
      --image-zoom-easing-out: steps(6, jump-none);
    }

Motion variables

Set them around a gallery, or on :root for the whole site. The animationDuration prop wins over the duration.

--image-zoom-animation-duration
The length of the zoom; the animationDuration prop wins over it
Default 300ms
--image-zoom-easing-in
The curve of the opening
Default cubic-bezier(0.2, 0, 0.2, 1)
--image-zoom-easing-out
The curve of the closing
Default cubic-bezier(0.4, 0, 0.2, 1)
--image-zoom-controls-duration
The fade of the buttons and the caption, after most of the zoom; three quarters of it when closing
Default 40% of the zoom
--image-zoom-controls-easing
Its curve
Default ease-out opening, ease-in closing
--image-zoom-slide-duration
The glide to the next image with the arrows and keys
Default 400ms
--image-zoom-slide-easing
Its curve
Default cubic-bezier(0.2, 0, 0, 1)
--image-zoom-caption-duration
The caption of each new image in a gallery coming in, and its rise on opening; 0s changes it at once
Default the slide
--image-zoom-caption-easing
Its curve
Default the curve of the slide
--image-zoom-caption-enter-opacity
The opacity a new caption starts from
Default 0
--image-zoom-caption-enter-x
A parallax: how far to the side a new caption starts, the side its image comes from
Default 0px
--image-zoom-caption-enter-y
A rise: how far below a new caption starts (above at the top), also on opening
Default 0px

Layout

Props choose where the navigation and the caption go. Spacing, corners and the size and shape of the controls are CSS variables: set them on any element around an<ImageZoom> to change that gallery only, or on :root for the whole site.

The default layout

  • The close button at the top right
  • The caption at the bottom, over the image
  • A bar with the arrows and the counter, in galleries of more than one photo

By default the arrows and the counter sit together in a bar at the bottom, easy to reach with a thumb.

  • Grey volcanic plain near Olympus Mons crossed by a long fissure shaped like a gecko, seen from orbit
    Pale rounded mounds with layered slopes on the floor of a depression on Mars, seen from orbit
    Computer-generated view of the curve of Mars at the line between night and day, with Gale Crater catching the morning light

    Arrows at the sides

    The arrows move to the screen edges; the counter stays at the bottom.

    <ImageZoom navigationLayout="sides">
  • Night lights of Seoul and the surrounding cities, seen from orbit
    Alan Bean climbing down the ladder of the lunar module onto the Moon, in shadow

    No counter

    Only the arrows in the bar, without the position in the gallery.

    <ImageZoom showCounter={false}>

Caption

The caption comes from data-image-zoom-caption (or the title of a data-image-zoom link), and sits at the bottom by default. How it changes from one image to the next is in Animation.

  • Hurricane Milton's eye and spiral of clouds over the Gulf of Mexico, seen from orbit

    Caption at the top

    Useful when the bottom of the photos holds the subject.

    <ImageZoom captionPosition="top">
  • Astronaut's bootprint pressed into the grey dust of the Moon

    No caption

    For photos that speak for themselves. The image keeps its alt text.

    <ImageZoom showCaption={false}>

Spacing and controls

  • Green aurora australis swirling above clouds over the Pacific, seen from orbit

    Padding and corners

    Room around the zoomed image, and rounded corners.

    .framed {
      --image-zoom-padding: 6vmin;
      --image-zoom-image-radius: 16px;
    }
  • Red and green aurora borealis shimmering above Canada, seen from orbit
    City lights on the night side of Earth under thousands of stars, with part of the space station

    Buttons and caption

    Square buttons, a flat caption in the accent color, everything closer to the edges.

    .custom-controls {
      --image-zoom-button-size: 38px;
      --image-zoom-button-radius: 2px;
      --image-zoom-caption-radius: 0;
      --image-zoom-controls-offset: 0.75rem;
      --image-zoom-caption-bg: #ff7a66;
      --image-zoom-caption-color: #131722;
    }
--image-zoom-padding
Space between the zoomed image and the screen edges
Default 0
--image-zoom-image-radius
Corners of the zoomed image
Default 0
--image-zoom-button-size
Size of the arrows and the close button
Default 40px (36px on phones)
--image-zoom-button-radius
Shape of the buttons and the navigation bar
Default 999px
--image-zoom-controls-offset
Distance from the controls and the caption to the screen edges
Default 16px (12px on phones)
--image-zoom-caption-max-width
Widest the caption can get
Default 70% (100% on phones)
--image-zoom-caption-font
Font family of the caption
Default inherit
--image-zoom-caption-font-size
Font size of the caption
Default 13px (12px on phones)
--image-zoom-caption-radius
Corners of the caption box
Default 10px

Screen sizes

On screens up to 640px wide the overlay makes its buttons, its distance to the edges and the caption text smaller, and lets the caption take the whole width. A variable you set wins on every screen: --image-zoom-button-size: 56px keeps 56px buttons on a phone too. Keep the large values for wide screens with a media query, or let them grow with the screen with clamp().

/* <ImageZoom class="gallery"> */
.gallery {
  --image-zoom-padding: clamp(12px, 5vw, 64px);
}

@media (width > 640px) {
  .gallery {
    --image-zoom-button-size: 56px;
    --image-zoom-controls-offset: 32px;
  }
}

The overlay copies your values each time a gallery opens: when a media query changes them, as when the phone turns with a photo open, the new ones apply from the next opening. The overlay's own smaller defaults follow the screen at once.

Theming

The overlay follows the light or dark preference of the system. To change its colors, the theme prop is enough, with no CSS to write. Everything else about its look, spacing and shapes too, is a CSS variable. How it moves is in Animation.

The theme prop

The colors of one gallery, straight on the component. Any CSS color works, and light-dark() gives one for each scheme.

<ImageZoom
  theme={{
    backgroundColor: 'light-dark(#f4f1ea, #14120f)',
    captionColor: 'light-dark(#1a1a1a, #f1ece4)',
    captionBackground: 'light-dark(#e8e1d4, #2a2622)',
  }}
>
backgroundColor
Overlay background: --image-zoom-bg
closeButtonColor
Close icon: --image-zoom-close-color
closeButtonBackground
Close button: --image-zoom-close-bg
navigationColor
Arrows and counter: --image-zoom-nav-color
navigationBackground
Navigation bar, or each arrow at the sides: --image-zoom-nav-bg
captionColor
Caption text: --image-zoom-caption-color
captionBackground
Caption box: --image-zoom-caption-bg

Each key sets the color variable beside it on that gallery, so it wins over the same variable in your CSS. The keys you leave out keep your CSS, or the defaults.

CSS variables

For the whole site, or for more than colors. When a gallery opens, the overlay takes the --image-zoom-* values set on any element around it: on :root for the whole site, or on any wrapper for the galleries inside it. A handful of them together make a theme: colors, the caption font, the shapes and the motion. The overview has six ready-made ones to try and copy.

/* The whole site */
:root {
  --image-zoom-bg: light-dark(#faf7f2, #161412);
  --image-zoom-caption-color: light-dark(#1a1a1a, #f1ece4);
  --image-zoom-caption-font: Georgia, serif;
  --image-zoom-button-radius: 0px;
  --image-zoom-animation-duration: 550ms;
  --image-zoom-easing-in: cubic-bezier(0.25, 1, 0.5, 1);
}

/* Only the galleries inside .portfolio */
.portfolio {
  --image-zoom-padding: 5vmin;
  --image-zoom-image-radius: 12px;
}

Colors

--image-zoom-bg
Overlay background
Default light-dark(rgba(255, 255, 255, 0.98), rgba(0, 0, 0, 0.95))
--image-zoom-close-color
Close icon
Default light-dark(rgba(0, 0, 0, 0.88), rgba(255, 255, 255, 0.92))
--image-zoom-close-bg
Close button, translucent over a blur
Default light-dark(rgba(255, 255, 255, 0.75), rgba(28, 28, 30, 0.7))
--image-zoom-nav-color
Arrows and counter
Default light-dark(rgba(0, 0, 0, 0.88), rgba(255, 255, 255, 0.92))
--image-zoom-nav-bg
Navigation bar (or each arrow in the sides layout), translucent over a blur
Default light-dark(rgba(255, 255, 255, 0.75), rgba(28, 28, 30, 0.7))
--image-zoom-caption-color
Caption text
Default light-dark(rgba(0, 0, 0, 0.88), rgba(255, 255, 255, 0.92))
--image-zoom-caption-bg
Caption box, translucent over a blur
Default light-dark(rgba(255, 255, 255, 0.75), rgba(28, 28, 30, 0.7))

Color scheme

--image-zoom-color-scheme
Set dark or light to follow your own theme toggle instead of the system
Default light dark

The layout variables are listed under Spacing and controls, and the motion ones under Motion variables.

Playground

Change a value and open a photo. The code to copy updates as you go; the variables only apply to this gallery.

Change a value, then open a photo.

Colors
Layout and motion
Animation
Easing
Caption
Navigation
Crab Nebula in purple, pink and yellow, combining five observatories
Planetary nebula IC 418, an orange shell with a violet center traced by fine patterns
/* Change a value to see the code */

Parts

The overlay lives in a shadow root, so the CSS of your site can't break it: generic rules such as button { all: unset } or svg { width: 1em } never reach it. The variables cross into it; for anything else, style its parts with::part().

astro-image-zoom-overlay::part(caption) {
  text-transform: uppercase;
}
overlay
The <dialog>
backdrop
The background behind the image
track
The carousel that holds the slides
slide, image
Each slide and its image
caption
The caption
close
The close button
toolbar
The navigation bar
nav, prev, next
The arrows (nav matches both)
counter
The position in the gallery

See the zoom with its default styles, and with hostile CSS that breaks the rest of the page.

Labels

Apart from the counter, which is only numbers, the texts the component adds are aria-labels, read by screen readers. They are in English; the labels prop translates the ones you set. The caption is your own text, so the component never translates it.

<ImageZoom labels={{ close: 'Cerrar zoom', enlargeNamed: 'Ampliar imagen: {alt}' }}>
  <img src="/photo.jpg" alt="Un coche rojo" />
</ImageZoom>
overlay
The dialog
Default Image zoom overlay
close
The close button
Default Close zoom overlay
images
The group of images
Default Images
previous
The previous image button
Default Previous image
next
The next image button
Default Next image
enlarge
The link the component adds around an image with no alt text
Default Enlarge image
enlargeNamed
The link the component adds around an image; {alt} is replaced with its alt text
Default Enlarge image: {alt}

For a multilingual site, wrap the component in one of your own that picks the labels of the page's locale:

Show code
---
// src/components/Zoom.astro
import ImageZoom from 'astro-image-zoom/ImageZoom.astro';
import type { ImageZoomLabels } from 'astro-image-zoom';

const translations: Record<string, Partial<ImageZoomLabels>> = {
  es: { close: 'Cerrar zoom', enlargeNamed: 'Ampliar imagen: {alt}' },
};
---
<ImageZoom {...Astro.props} labels={translations[Astro.currentLocale ?? '']}>
  <slot />
</ImageZoom>

Events

Each <astro-image-zoom> dispatches an event when the zoom opens, moves to another image, starts to close and has closed, for analytics or to sync something else on the page. They bubble, so one listener on the document hears every gallery. Open a photo and watch the log.

Saturn backlit by the Sun, its rings glowing around the dark planet
Saturn and its rings in natural color
Pluto in enhanced color, with a pale heart-shaped plain and reddish regions

Event log

    Open a photo and move through the gallery to see its events here.

    <script>
      document.addEventListener('astro-image-zoom:open', (event) => {
        const { index, total, src } = event.detail;
        console.log(`Opened ${index + 1} of ${total}: ${src}`);
      });
    
      // Only one gallery: listen on its element instead
      document.querySelector('.portfolio')?.addEventListener('astro-image-zoom:change', (event) => {
        console.log('Now showing', event.detail.caption);
      });
    </script>
    astro-image-zoom:open
    A zoom starts to open (a click, Enter on a link), before its image has loaded
    astro-image-zoom:change
    The gallery moves to another image (arrows, keys, a swipe). Not dispatched on open
    astro-image-zoom:close
    The zoom starts to close, however it closes
    astro-image-zoom:closed
    The zoom has closed: the closing animation has ended and the image is back on the page

    Event detail

    Every event carries the image on screen in its detail, typed as ZoomEventDetail.

    index
    Position of the image in its gallery, from 0
    number
    total
    Number of images in the gallery
    number
    src
    URL of the image the zoom shows
    string
    alt
    Alt text of the image
    string
    caption
    Caption, or an empty string
    string
    link
    The link on the page that opens this image
    HTMLElement

    JavaScript API

    For images outside any <ImageZoom>, such as markup your scripts add after the page loads, create a zoom with ZoomClass on the element around the links. Images aren't wrapped then, so only links with data-image-zoom count. Inside an <ImageZoom> you don't need it: links with data-image-zoom added later are picked up when clicked.

    <div class="my-gallery">
      <a href="/large-1.jpg" data-image-zoom><img src="/small-1.jpg" alt="Harbor at dawn" /></a>
      <a href="/large-2.jpg" data-image-zoom><img src="/small-2.jpg" alt="Harbor at noon" /></a>
    </div>
    
    <script>
      import { ZoomClass } from 'astro-image-zoom';
    
      const gallery = document.querySelector<HTMLElement>('.my-gallery');
      if (gallery) {
        const zoom = new ZoomClass(gallery);
        // Later, if needed: zoom.destroy();
      }
    </script>

    It reads the options from the same data-* attributes <ImageZoom> renders on its element, such asdata-image-zoom-show-counter="false"; the theme and the duration come from the --image-zoom-* variables.data-image-zoom-ignore-selector on the wrapper takes any CSS selector, since the browser matches it.

    Reference

    Props

    ignore
    Images left out of the zoom and the gallery: simple selectors (tag, .class, #id, [attribute]) matched on each image and the elements around it
    string · Default ""
    showNavigation
    Arrows and counter in galleries; keys and swipes work without them
    boolean · Default true
    closeOnBackdrop
    A click beside the image closes it
    boolean · Default true
    closeOnImage
    A click on the image closes it
    boolean · Default true
    closeOnScroll
    A wheel or touchpad scroll, or a vertical swipe, closes it
    boolean · Default true
    animation
    How the image opens and closes: it grows from its thumbnail, or fades in where it lands
    "zoom" | "fade" · Default "zoom"
    animationDuration
    Milliseconds; overrides --image-zoom-animation-duration
    number · Default 300
    navigationLayout
    Arrows and counter in a bar at the bottom, or arrows at the sides of the screen
    "bar" | "sides" · Default "bar"
    showCounter
    Position in the gallery, such as “3 / 8”
    boolean · Default true
    captionPosition
    Where the caption sits on the screen
    "bottom" | "top" · Default "bottom"
    showCaption
    Caption of the zoomed image
    boolean · Default true
    theme
    The colors of this gallery, a key per color variable (see Theming); it wins over your CSS
    object · Default {}
    labels
    Texts read by screen readers, key by key; the keys you leave out stay in English
    Partial<ImageZoomLabels> · Default English
    class
    Class for the <astro-image-zoom> element
    string

    Image attributes

    data-image-zoom-src
    Full-size image for the zoom. Needed when the file on the page is a smaller version
    data-image-zoom-caption
    Caption shown with the zoomed image; on the <a> itself for a link with data-image-zoom, where its title works too
    data-image-zoom-width
    Width in pixels of the full-size file. With the height, the zoom opens with its final shape at once instead of waiting for the file
    data-image-zoom-height
    Height in pixels of the full-size file
    data-image-zoom
    On an <a href> around an image: the zoom opens its href. The component leaves the link as it is
    data-image-zoom-ignore
    On an image or any element around it: left out of the zoom and the gallery, like the ignore prop for a single image