![Stacy Kvernmo](https://web.dev/images/authors/stacykvernmo.jpg) Stacy Kvernmo [Bluesky](https://bsky.app/profile/stacykvernmo.com) [Homepage](https://oddbird.net/authors/stacy/) Published: October 29, 2025
From image sharing sites to online stores, image galleries are a common pattern on the web. Images can be very data heavy, and loading images can make the page take a long time to load. In addition, users have high expectations around the usability of galleries, so it's common to add additional libraries that further increase page size. The web platform has added support for many of the underlying pieces of an image gallery. So, what does it look like to code an image gallery with Baseline features? This demo showcases a variety of techniques that you can use to do just that. > [!NOTE] > **Note:** This demo is also [available on GitHub](https://github.com/GoogleChromeLabs/baseline-demos/tree/main/src/image-gallery). ## How to deal with large image sizes Images can be some of the largest assets you ask your users to download, and image galleries by their nature often have many images. This demo uses a couple of Baseline features to help reduce the performance impact on users. ### Lazy loading Loading all of the images when the page loads can make the other content slower to load overall. It's a useful pattern to defer loading of images that aren't on the screen until they are on the screen. But it's a balance---you don't want users to have to wait for images to load as they scroll. You want them to already be loaded when they scroll into view. JavaScript libraries have made this possible in the past, and you could also roll your own with an IntersectionObserver. However, both options mean shipping more code, and leave more room for bugs. Browsers have made this possible with an HTML-based progressive enhancement: By adding `loading="lazy"` to `` elements, the browser will defer loading those images until they are needed. If you have a sense of how many images will be seen on screens when the page is first loaded, you can set `loading="eager"` on the first few images, to make sure that those are loaded immediately. Because `loading="eager"` is the default, you can also just omit the attribute for those images. If you view the Network panel in your browser's developer tools as you load the demo, only the first six will load immediately. Depending on your screen size and how many are visible, several others may be loaded. As you scroll, the browser will load the remaining images. Lazy loading images works with more than just scrolling. If an image is initially hidden---for example, in a dialog---the image won't load until the dialog is opened. This would be useful in an image gallery if you are loading a larger image size when the user clicks on an image. When you add lazy loading to your images, make sure that you are providing dimensions for the image. This prevents a layout shift if the image doesn't get loaded in time. In this demo, the inline size is determined by the grid definition, and the `aspect-ratio` CSS property on the image gallery grid items is set to `1 / 1`, so the block size matches that. You can also [set dimension attributes](https://web.dev/articles/browser-level-image-lazy-loading.md.txt#dimension-attributes) directly. ### AVIF > [!NOTE] > **Note:** To learn more about using images on the web, check out the [Learn Images course](https://web.dev/learn/images.md.txt). While you want to show your users high resolution images, you likely don't want to show them the full resolution image, especially in the gallery of thumbnails. You'll want to either compress and resize your images before uploading to your server, or configure your server to resize images for you. The AVIF file format is a relatively new format that can be an alternative to legacy formats such as JPEG and PNG, and is worth investigating for potential loading performance benefits. Along with supporting animated images and transparency, AVIF can have lower file sizes than other image formats. The images in this demo were converted to AVIF from JPG, and are much smaller while retaining suitable image quality. AVIF also supports HDR images. Online tools like [Squoosh](https://squoosh.app) and [Cloudinary](https://cloudinary.com/tools/image-to-avif) are useful for one-off conversions to AVIF if you're looking to experiment with the format. Design tools such as Photoshop (version 26+) and GIMP also export to AVIF. You can also incorporate AVIF encoding in your image processing pipelines using [ImageMagick](https://imagemagick.org/script/formats.php/#supported). ## Lightbox effect In an image gallery, users have the expectation that they can click an image to view a larger version. In the past, this often required `z-index` hacks, but now you can use the `` element, which is Baseline Widely available. Built with accessibility in mind, the `` element handles focus management more effectively, and requires less custom JavaScript. A dialog places your content in a new top layer, on top of everything else. To create the lightbox effect, you can use the `::backdrop` pseudo element. This is a styleable box below the dialog, but above the rest of the page. This all works without you needing to worry about the `z-index` of anything. ### Transition the lightbox By default, a dialog appears and disappears with no transition effects. Adding some slight transitions can make the experience feel more smooth, and help the user mentally transition. The demo uses `allow-discrete` transition behavior and `@starting-style` for the dialog to define the transition for the dialog. ## Style the button ### Backdrop filter A common design pattern for image galleries is to place text on top of the image. This comes with the risk that the image won't provide sufficient contrast with the text, making the text difficult or impossible to read. One way of handling that is to add a semi-transparent background behind the text, but this doesn't always provide the needed effect. The `backdrop-filter` CSS property gives you more control over the effect. With `backdrop-filter`, you can combine color effects and blurs that apply to the content behind the `` element. You can also use pseudo classes to update the filter when the button is hovered or focused. ```css button { --btn-filter: blur(1em); backdrop-filter: var(--btn-filter); &:hover, &:focus { --btn-filter: blur(0.75em) saturate(350%); } } ``` ### Resolution media query The demo also uses a `resolution` media query to add a bit of extra polish. The button's top border is `1px`, which will serve as a default size, but you can choose to display a subpixel border on higher resolution screens. ```css @media (min-resolution: 2x) { --border-size: 0.5px; } ``` ## Aspect ratio For the images to be displayed in a consistent size, you can set an aspect ratio. This works best when paired with `object-fit` to instruct the image how best to fill the space. ```css [data-img] { aspect-ratio: 1 / 1; object-fit: cover; } ``` The gallery example uses an aspect ratio of `1 / 1` meaning the width and height will be equal. The width comes from `grid-template-columns` which has a minimum size of `16em`, but can grow until there is enough room to add another column. The height then matches the width. With an object-fit value of `cover`, this will ensure each image fills its container in both dimensions maintaining its intrinsic aspect ratio, and will be cropped if it's overflowing. As you saw in the section on lazy loading images, this demo also uses `aspect-ratio` to make sure an image doesn't change dimensions when it loads, preventing a layout shift. ## Take it further There are other Baseline features that you may want to incorporate into your image gallery. If you add navigation to the previous and next images from within the dialog, you may want to animate the change with [view transitions](https://web.dev/learn/css/view-transitions-spas.md.txt). If you have the ability to generate multiple sizes of the images, you can use [the `` element](https://developer.mozilla.org/docs/Web/HTML/Reference/Elements/picture) to serve different resolutions of images on different screen sizes. Baseline web features are making it possible to make a performant and usable image gallery with less code, and without relying on additional libraries. The next time you need to build an image gallery, you can use this demo as a pattern, or you can adopt pieces of it to enhance your current tools today.