Usage
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.
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>Links
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.

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: .
// 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.
No arrows or counter
Keys and swipes still move through the gallery.
<ImageZoom showNavigation={false}>Stays open on a backdrop click
A click on the backdrop does nothing; the close button and Escape still work.
<ImageZoom closeOnBackdrop={false}>Stays open on an image click
A click on the zoomed image does nothing.
<ImageZoom closeOnImage={false}>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.
Faster or slower
The length of the zoom in milliseconds: 150 on the left, 800 on the right.
<ImageZoom animationDuration={150}> <ImageZoom animationDuration={800}>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">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; }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.
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); }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); }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); }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); }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); }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.
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
Navigation
By default the arrows and the counter sit together in a bar at the bottom, easy to reach with a thumb.
Arrows at the sides
The arrows move to the screen edges; the counter stays at the bottom.
<ImageZoom navigationLayout="sides">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.
Caption at the top
Useful when the bottom of the photos holds the subject.
<ImageZoom captionPosition="top">No caption
For photos that speak for themselves. The image keeps its alt text.
<ImageZoom showCaption={false}>
Spacing and controls
Padding and corners
Room around the zoomed image, and rounded corners.
.framed { --image-zoom-padding: 6vmin; --image-zoom-image-radius: 16px; }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; }
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)',
}}
>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
--image-zoom-close-color- Close icon
--image-zoom-close-bg- Close button, translucent over a blur
--image-zoom-nav-color- Arrows and counter
--image-zoom-nav-bg- Navigation bar (or each arrow in the sides layout), translucent over a blur
--image-zoom-caption-color- Caption text
--image-zoom-caption-bg- Caption box, translucent over a blur
Color scheme
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.
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;
}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>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.
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>Event detail
Every event carries the image on screen in its detail, typed as ZoomEventDetail.
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.









































