Image zoom for Astro

Click or tap any photo on this page. It grows from its place to fill the screen, and a group of photos becomes a gallery you can swipe.

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
  • Keyboard and touch
  • No dependencies
  • Accessible
Read the docs
Ridge of glowing orange gas and dust in the Carina Nebula under a blue sky full of stars
Saturn V rocket lifting off beside its launch tower in a cloud of flame and smoke
Astronaut in a white spacesuit working on the gold-foil body of the Hubble Space Telescope
The space station with the space shuttle Endeavour docked to it, above the curve of Earth
Center of the Milky Way glowing in red, blue and yellow, combined from three space telescopes
Wide panorama of rocky Martian ground and distant hills under a hazy sky

Wherever your images are

Inside an article

Photos in the flow of text. Smooth liftoff, soft landing: the zoom starts from the image itself and lands back on it, so the eye never loses it.

On Christmas Eve 1968, Apollo 8 came around the far side of the Moon, and Bill Anders saw the Earth rise over its horizon.

Earth, half in shadow, rising above the grey horizon of the Moon
EarthriseApollo 8 · 1968

He asked for a roll of color film and took the photo in a hurry, before the Earth moved out of the window.

A gallery

All the images inside one <ImageZoom> form a gallery. Move with the arrows, the ← →keys or a swipe.

Thousands of galaxies of many shapes and colors around the galaxy cluster SMACS 0723
Sombrero galaxy seen edge-on, a bright white core crossed by a dark band of dust
Bubble Nebula: a blue bubble of gas blown by a massive star, among clouds of orange and teal
Horsehead Nebula in infrared, a dark tower of gas and dust shaped like a horse's head
Heart of the Lagoon Nebula: billowing golden clouds of gas lit by a young star
Cassiopeia A, the remains of an exploded star, a shell of pink, orange and blue filaments
Whirlpool galaxy, a spiral with pink star-forming regions along its arms
Helix Nebula, a ring of orange and blue gas around a dying star, like an eye

Several galleries

Each <ImageZoom> is its own gallery: the arrows only move through the photos of the one you opened.

Earth from orbit

Green and red aurora over the dark curve of the Earth, seen from orbit
Spiral of clouds of Hurricane Helene over the sea, seen from orbit
City lights along the coasts of north Africa and southern Europe at night, seen from orbit

Mars

Perseverance rover beside the small Ingenuity helicopter on reddish Martian ground
Hill called Santa Cruz rising above a rock-strewn Martian plain
Perseverance rover selfie on a flat Martian plain, with sample tubes left on the ground

The Moon

Buzz Aldrin walking on the Moon near a leg of the lunar module
Buzz Aldrin standing beside the U.S. flag on the Moon
Harrison Schmitt beside the U.S. flag on the Moon, with Earth small in the black sky

Make it yours

Six ready-made themes, from everyday to just for fun. Each is a handful of --image-zoom-* variables: colors for light and dark mode, caption font, spacing, the shape of the controls and the motion, plus a prop or two for the layout. Pick one, open a photo, copy the CSS: on :root for the whole site, or on one gallery as here.

Theme

Darkroom

Expo fade · 500ms

For photographers: nothing but the picture, almost edge to edge on white or black, no counter, and controls that fade in slowly.

Two colliding galaxies twisted into one swirl of blue stars, pink star-forming clouds and brown dust lanes
Clouds of glowing blue gas and dark brown dust, scattered with orange and white stars, in the Large Magellanic Cloud
.darkroom {
  --image-zoom-bg: light-dark(#ffffff, #000000);
  --image-zoom-close-color: light-dark(#111111, #f2f2f2);
  --image-zoom-close-bg: light-dark(rgb(236 236 236 / 0.82), rgb(38 38 38 / 0.82));
  --image-zoom-nav-color: light-dark(#111111, #f2f2f2);
  --image-zoom-nav-bg: light-dark(rgb(236 236 236 / 0.82), rgb(38 38 38 / 0.82));
  --image-zoom-caption-color: light-dark(#111111, #f2f2f2);
  --image-zoom-caption-bg: light-dark(rgb(255 255 255 / 0.82), rgb(26 26 26 / 0.82));
  --image-zoom-caption-font-size: 12px;
  --image-zoom-caption-radius: 999px;
  --image-zoom-button-size: 36px;
  --image-zoom-button-radius: 999px;
  --image-zoom-padding: 2vmin;
  --image-zoom-image-radius: 0px;
  --image-zoom-controls-offset: 16px;
  --image-zoom-animation-duration: 500ms;
  --image-zoom-easing-in: cubic-bezier(0.16, 1, 0.3, 1);
  --image-zoom-easing-out: cubic-bezier(0.7, 0, 0.84, 0);
  --image-zoom-slide-duration: 600ms;
  --image-zoom-slide-easing: cubic-bezier(0.16, 1, 0.3, 1);
  --image-zoom-controls-duration: 700ms;
  --image-zoom-controls-easing: cubic-bezier(0.16, 1, 0.3, 1);
  --image-zoom-caption-duration: 400ms;
}

/* <ImageZoom class="darkroom" animation="fade" navigationLayout="sides" showCounter={false}> */

Editorial

Quart · 600ms

For long reads: cream paper or a dark page, a serif caption set like a printed one above the photo, wide margins and a claret accent.

Katherine Johnson at her desk, working with a pencil on sheets of figures, beside a celestial globe
Katherine Johnson in glasses and a patterned scarf, typing at a computer terminal
.editorial {
  --image-zoom-bg: light-dark(#f6f1e7, #1b1714);
  --image-zoom-close-color: light-dark(#ffffff, #1b1714);
  --image-zoom-close-bg: light-dark(rgb(122 31 43 / 0.82), rgb(232 168 160 / 0.82));
  --image-zoom-nav-color: light-dark(#ffffff, #1b1714);
  --image-zoom-nav-bg: light-dark(rgb(122 31 43 / 0.82), rgb(232 168 160 / 0.82));
  --image-zoom-caption-color: light-dark(#1f1a17, #efe6d8);
  --image-zoom-caption-bg: light-dark(rgb(246 241 231 / 0.82), rgb(27 23 20 / 0.82));
  --image-zoom-caption-font: "Iowan Old Style", "Palatino Linotype", Palatino, Georgia, serif;
  --image-zoom-caption-font-size: 17px;
  --image-zoom-caption-max-width: 560px;
  --image-zoom-caption-radius: 0px;
  --image-zoom-button-size: 40px;
  --image-zoom-button-radius: 0px;
  --image-zoom-controls-offset: 20px;
  --image-zoom-padding: 10vmin;
  --image-zoom-image-radius: 0px;
  --image-zoom-animation-duration: 600ms;
  --image-zoom-easing-in: cubic-bezier(0.25, 1, 0.5, 1);
  --image-zoom-easing-out: cubic-bezier(0.5, 0, 0.75, 0);
  --image-zoom-slide-duration: 600ms;
  --image-zoom-slide-easing: cubic-bezier(0.25, 1, 0.5, 1);
  --image-zoom-caption-enter-x: 120px;
}

/* <ImageZoom class="editorial" captionPosition="top"> */

Museum

Slow quart · 750ms

For art and archives: a warm grey or deep green wall, a lot of room around the picture, a small label plate and brass controls, in no hurry.

Two interacting galaxies shaped like a rose: a spiral twisted by a smaller galaxy below it, its stem
An astronaut's gold visor reflecting her own spacesuit and camera, with the space station and Earth around
.museum {
  --image-zoom-bg: light-dark(#e6e1d6, #1c2621);
  --image-zoom-close-color: light-dark(#ffffff, #1c2621);
  --image-zoom-close-bg: light-dark(rgb(94 72 24 / 0.82), rgb(212 178 106 / 0.82));
  --image-zoom-nav-color: light-dark(#ffffff, #1c2621);
  --image-zoom-nav-bg: light-dark(rgb(94 72 24 / 0.82), rgb(212 178 106 / 0.82));
  --image-zoom-caption-color: light-dark(#2b2a26, #1c2621);
  --image-zoom-caption-bg: light-dark(rgb(251 248 241 / 0.82), rgb(244 239 226 / 0.82));
  --image-zoom-caption-font: "Iowan Old Style", "Palatino Linotype", Palatino, Georgia, serif;
  --image-zoom-caption-font-size: 13px;
  --image-zoom-caption-max-width: 320px;
  --image-zoom-caption-radius: 2px;
  --image-zoom-button-size: 40px;
  --image-zoom-button-radius: 2px;
  --image-zoom-controls-offset: 24px;
  --image-zoom-padding: 12vmin;
  --image-zoom-image-radius: 0px;
  --image-zoom-animation-duration: 750ms;
  --image-zoom-easing-in: cubic-bezier(0.25, 1, 0.5, 1);
  --image-zoom-easing-out: cubic-bezier(0.5, 0, 0.75, 0);
  --image-zoom-slide-duration: 800ms;
  --image-zoom-slide-easing: cubic-bezier(0.25, 1, 0.5, 1);
  --image-zoom-caption-duration: 500ms;
  --image-zoom-caption-enter-y: 6px;
}

/* <ImageZoom class="museum" navigationLayout="sides" showCounter={false}> */

Blueprint

Mechanical · 220ms

For maps, diagrams and technical docs: blueprint blue, monospaced labels, a counter to keep your place and a quick, mechanical zoom.

Map of Gale Crater with the red line of Curiosity's drive from Yellowknife Bay to Pahrump Hills, with labeled waypoints
A view across the layered slopes of Mount Sharp with a white line tracing Curiosity's planned path
.blueprint {
  --image-zoom-bg: light-dark(#e8f0fb, #0a2a5e);
  --image-zoom-close-color: light-dark(#ffffff, #0a2a5e);
  --image-zoom-close-bg: light-dark(rgb(11 61 145 / 0.82), rgb(219 232 255 / 0.82));
  --image-zoom-nav-color: light-dark(#ffffff, #0a2a5e);
  --image-zoom-nav-bg: light-dark(rgb(11 61 145 / 0.82), rgb(219 232 255 / 0.82));
  --image-zoom-caption-color: light-dark(#0b3d91, #ffffff);
  --image-zoom-caption-bg: light-dark(rgb(255 255 255 / 0.82), rgb(13 58 122 / 0.82));
  --image-zoom-caption-font: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
  --image-zoom-caption-font-size: 12px;
  --image-zoom-caption-radius: 2px;
  --image-zoom-button-size: 36px;
  --image-zoom-button-radius: 2px;
  --image-zoom-controls-offset: 16px;
  --image-zoom-padding: 5vmin;
  --image-zoom-image-radius: 0px;
  --image-zoom-animation-duration: 220ms;
  --image-zoom-easing-in: cubic-bezier(0.2, 0, 0, 1);
  --image-zoom-easing-out: cubic-bezier(0.3, 0, 1, 1);
  --image-zoom-slide-duration: 200ms;
  --image-zoom-slide-easing: linear;
  --image-zoom-caption-duration: 0ms;
}

/* <ImageZoom class="blueprint"> */

Arcade

8-bit steps · 450ms

Hot pink, cyan and yellow on deep purple, square pixels and a zoom in five frames, like an 8-bit game.

Jupiter with its bands and Great Red Spot, a glowing blue aurora around its north pole
Two views of the pale blue planet Uranus with its faint rings, a small white aurora on each
.arcade {
  --image-zoom-bg: light-dark(#fff0fa, #16062c);
  --image-zoom-close-color: light-dark(#ffffff, #1a0628);
  --image-zoom-close-bg: light-dark(rgb(168 14 95 / 0.82), rgb(255 92 184 / 0.82));
  --image-zoom-nav-color: light-dark(#ffffff, #1a0628);
  --image-zoom-nav-bg: light-dark(rgb(7 85 96 / 0.82), rgb(62 230 245 / 0.82));
  --image-zoom-caption-color: light-dark(#ffe74c, #1a0628);
  --image-zoom-caption-bg: light-dark(rgb(59 10 92 / 0.82), rgb(255 231 76 / 0.82));
  --image-zoom-caption-font: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
  --image-zoom-caption-font-size: 12px;
  --image-zoom-caption-radius: 0px;
  --image-zoom-button-size: 48px;
  --image-zoom-button-radius: 0px;
  --image-zoom-padding: 5vmin;
  --image-zoom-image-radius: 0px;
  --image-zoom-animation-duration: 450ms;
  --image-zoom-easing-in: steps(5, jump-none);
  --image-zoom-easing-out: steps(5, jump-none);
  --image-zoom-slide-duration: 360ms;
  --image-zoom-slide-easing: steps(4, jump-none);
  --image-zoom-controls-duration: 200ms;
  --image-zoom-controls-easing: steps(2, jump-none);
  --image-zoom-caption-duration: 0ms;
}

/* <ImageZoom class="arcade" captionPosition="top" navigationLayout="sides"> */

Bubblegum

Spring · 400ms

Playful and soft: candy pink or plum, big round buttons, round photos and a springy zoom that overshoots and settles.

Astronaut Scott Kelly holding up a floating bag full of colorful candies inside the space station
Astronaut Chris Hadfield in a red shirt playing guitar in the cupola, Earth in the windows
.bubblegum {
  --image-zoom-bg: light-dark(#ffe4f1, #2a0f2e);
  --image-zoom-close-color: light-dark(#ffffff, #2a0f2e);
  --image-zoom-close-bg: light-dark(rgb(173 20 87 / 0.82), rgb(255 179 220 / 0.82));
  --image-zoom-nav-color: light-dark(#ffffff, #2a0f2e);
  --image-zoom-nav-bg: light-dark(rgb(173 20 87 / 0.82), rgb(255 179 220 / 0.82));
  --image-zoom-caption-color: light-dark(#4a0d33, #2a0f2e);
  --image-zoom-caption-bg: light-dark(rgb(255 255 255 / 0.82), rgb(255 240 247 / 0.82));
  --image-zoom-caption-font-size: 15px;
  --image-zoom-caption-radius: 999px;
  --image-zoom-button-size: 56px;
  --image-zoom-button-radius: 999px;
  --image-zoom-controls-offset: 28px;
  --image-zoom-padding: 7vmin;
  --image-zoom-image-radius: 28px;
  --image-zoom-animation-duration: 400ms;
  --image-zoom-easing-in: linear(0, 0.041 3%, 0.143 6%, 0.283 9%, 0.438 12%, 0.642 16%, 0.819 20%, 0.984 25%, 1.082 30%, 1.122 35%, 1.122 40%, 1.093 46%, 1.054 52%, 1.020 58%, 0.995 65%, 0.985 72%, 0.986 80%, 0.994 90%, 1);
  --image-zoom-slide-duration: 400ms;
  --image-zoom-slide-easing: cubic-bezier(0.34, 1.56, 0.64, 1);
  --image-zoom-caption-duration: 400ms;
  --image-zoom-caption-easing: cubic-bezier(0.34, 1.56, 0.64, 1);
  --image-zoom-caption-enter-y: 20px;
}

/* <ImageZoom class="bubblegum" navigationLayout="sides"> */

Built in

  • Keyboard

    Tab to a photo and press Enter; the arrow keys move, and Escape closes with the focus on the photo you ended on.

  • Screen readers

    A native dialog with labelled controls; each image keeps its alt text, and the caption is announced as you move.

  • Touch and touchpad

    Swipe between photos with the inertia of a real carousel; a vertical swipe or a scroll closes the zoom.

  • Works without JavaScript

    Each photo is wrapped in a link to the file the zoom opens, so it opens even before the script loads.

  • Safe from your CSS

    A shadow root keeps your styles out of the zoom and the zoom out of your page; you change it on purpose, with CSS variables and parts.

  • Motion you can tune

    Zoom or fade, any CSS easing from springs to steps, and captions that glide in with each photo; with reduced motion, it all stays still.

Get started

  1. 1. Install

    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
  2. 2. Wrap your images

    Every image inside opens in the zoom. When the page shows a smaller file, such as a thumbnail or Astro's <Image>, give the zoom the full-size one: see how. On a Starlight site, the plugin does it with one line in the config.

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

    Options for the navigation, the caption and how it closes; colors, spacing, shapes and motion with CSS variables.

    Read the docs