Fisheye Grid Gallery

1. Add to your HTML <head>:

In your downloadThe working code for this step, in index.html.

2. Add before the closing </body> tag:

In your downloadThe working code for this step, in index.html.

3. Add the gallery anywhere in your <body>:

In your downloadThe working code for this step, in index.html.

Give it a height (see below) and it is done. Each link points at the full-size file, which only loads when the viewer opens it.

What the effect needs from your markup: a [data-fisheye-grid] element containing a .fisheye__grid list of .fisheye__cell items, each holding one a.fisheye__item whose href is the full-size image and which wraps an <img> thumbnail. data-width and data-height on the link give the full image's shape, so the viewer can size the photo before the file arrives (without them it uses the thumbnail's shape). The caption is optional: the script reads data-caption on the link, then the .fisheye__caption text, then the image's alt. Any button inside the gallery with data-fisheye-magnify="2.2" (or another number) becomes a lens strength switch with an aria-pressed state; the demo's Soft / Medium / Strong row is just three of those.

What is only the demo's styling: the Hanken Grotesk font, the grey palette, the hint line, the lens control row and its pill styling, the caption chip, the viewer's round buttons and the full-window .showcase-shell layout. Delete or restyle any of it. The tokens at the top of .fisheye set the gutter (--fisheye-gap, 3px), corner radius (--fisheye-radius) and empty-cell colour (--fisheye-cell).

CSS the effect depends on:

• A height. The grid fills a fixed box and the script only redistributes it. Set --fisheye-height on .fisheye (default min(80vh, 760px)), or give the element a height in your layout and set --fisheye-height: auto as the demo does. The rows share that height evenly at rest.
• The .has-js .fisheye__grid rules: display: grid, minmax(0, 1fr) tracks, overflow: hidden and the --fisheye-columns container queries (8 columns, 6 below 900px, 4 below 600px of gallery width). Change the breakpoints or counts there, or set data-columns.
• Cells that clip and photos that cover: .fisheye__cell is position: relative; overflow: hidden and the image is object-fit: cover at 100% by 100%, so a growing cell reveals more of the photo rather than stretching it.
• touch-action: pan-y pinch-zoom on the grid, which lets the script decide when a finger drag is the loupe (see Touch below).
• The viewer is drawn inside the gallery element (position: absolute; inset: 0), so .fisheye must stay position: relative.

Set these as data attributes on the [data-fisheye-grid] element.

• Keyboard: the grid is one tab stop. Arrow keys walk a focus cursor cell to cell, Home and End jump to the ends of the row (with Ctrl, to the first and last photo), and the swell follows the cursor, so keyboard visitors see the same magnified photo and caption. Enter or Space opens the viewer.
• Viewer: a labelled modal dialog. Focus moves to Close, Tab cycles its three buttons, the rest of the gallery is made inert, arrow keys step through the set, and Escape, Close or a click outside the photo closes it and returns focus to the photo's link. A polite live region announces "20 / 48" and the caption on each step.
• Screen readers: the gallery stays an ordinary list of links named by each image's alt text; the visible caption is aria-hidden so it is not read twice.
• Touch: see data-touch. A tap opens the viewer; after a loupe drag the magnified photo holds for a moment and then the grid settles. In the viewer, swipe left or right to step.
• Reduced motion: no fisheye and no easing. The grid stays even, the focused photo gets a quiet two-tone ring and its caption, and the viewer opens, steps and closes with short crossfades. Changing the preference while the page is open rebuilds the gallery in the other mode.
• No JavaScript: the gallery is a plain responsive grid of linked thumbnails with their captions, and every photo links to its full-size file.

The demo ships 48 photographs as baked WebP derivatives in assets/img/: gNN.webp thumbnails (432 by 324, or 360 by 480 for portrait subjects, about 760 KB for all 48) that load up front, and gNN-full.webp files (1600px on the long edge, at the photo's own shape) that load only when the viewer opens a photo, together with its two neighbours. They are from Pexels and Unsplash and used under the Pexels License and the Unsplash License. Replace them with your own photographs for production; the gallery works with any number.

To regenerate or change them, edit assets/img-manifest.json and run bun scripts/build-template-assets.ts fisheye-grid-gallery from a GSAP Vault checkout, or export your own thumbnails at a size that covers the magnified cell (about 450px wide at the default strength in a 1200px wide gallery).

Required:

• GSAP 3.12+ (core only). One GSAP ticker eases the lens and stops once it has settled; GSAP timelines carry the photo into and out of the viewer; GSAP's context and media queries handle the reduced-motion rebuild and revert(). The demo is pinned to GSAP 3.15.0.

No plugins, no Lenis and no other libraries.

All current browsers (CSS grid, container queries and the inert attribute). Each frame of the lens rewrites two grid-template values on one element, so the cost is one layout of the grid's cells; it stays smooth with 48 photos and comfortably beyond. Nothing runs while the grid is at rest. Keep thumbnails small (around 10 to 25 KB each), since all of them load up front, and keep full-size files for the viewer.