> For the complete documentation index, see [llms.txt](https://staylime.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://staylime.com/docs/avante-themes/sections/media/image-grid.md). # Image grid A gallery of extra images pulled from the custom.gallery metafield — masonry or fixed-ratio grid with an optional zoom lightbox. Image grid is a second gallery further down the page: detail shots, process pictures, a lookbook. You set the section up once. After that, adding images is an admin job. The images come from the `custom.gallery` metafield on a product, page, blog, blog post or collection. {% hint style="info" %} **Theme Editor → Add section → Media → Image grid** On a blog post, the same gallery is an **Image grid** block inside the Blog post section, not a separate section. {% endhint %} *** ### How to add {% stepper %} {% step %} #### Choose the resource In the Shopify admin, go to **Settings → Custom data** and choose where the gallery lives: **Products**, **Pages**, **Blogs**, **Blog posts** or **Collections**. {% endstep %} {% step %} #### Create the metafield Click **Add definition**. Set the namespace and key to `custom.gallery` and the type to **File**, with **List of values** enabled, accepting images. {% endstep %} {% step %} #### Add the images Open a product, page or blog post and add the images to that metafield, in the order you want them shown. {% endstep %} {% step %} #### Add the section In **Customize**, open the matching template, click **Add section** and choose **Image grid** from the Media category. {% endstep %} {% endstepper %} {% hint style="warning" %} Without the metafield the section shows eight placeholder images in the theme editor and renders nothing on the live storefront. If a gallery is missing, check the metafield on that specific product first. {% endhint %} *** ### Good to know * **The editor is not a preview of the live page here.** Placeholders only appear inside Customize. On the published store the section either shows the metafield images or produces no output: no empty block, no padding. * **Which metafield is read depends on the template.** On a product template it reads the product's `custom.gallery`, on a page the page's, on a blog or blog post the blog's or the article's, on a collection the collection's. The home page, cart, search and account templates match none of these, so the section is empty there unless you use the **Page** setting to point at a page that has the metafield. * **Only images are rendered.** Videos, PDFs and other files in the metafield list are dropped, so a gallery can come out shorter than the list in the admin. * **The Original ratio uses a masonry layout.** Images keep their own proportions and are packed by height. The layout is calculated after the images load, so on a slow connection the grid may briefly settle into place. Every other ratio is a plain grid and crops to the ratio you chose around the **Focal point**. * **A single image forces a one-column mobile layout**, whatever the mobile setting says. * **The zoom style changes what the other zoom settings do.** With the default or slideshow style the images open in a lightbox. With the zoom-in style they magnify on hover, and the lightbox never opens. The overlay, media ratio, image width and mobile arrow settings then have no effect. * **The zoom has its own ratio and focal point.** **Media ratio** and the **Focal point** inside the zoom group crop the enlarged image independently of the grid, so a square grid thumbnail can open as a tall full-length shot. **Overlay** follows the store's default backdrop until you override it here with your own colour, opacity and background blur. * **Add only one Image grid block per blog post.** Two blocks on the same article share one lightbox, so clicking an image in the second grid opens the images from the first. * **Desktop and mobile switch at different widths.** The number of columns changes to the mobile value at 500 px, while the section paddings change at 920 px. Tablet-width screens use desktop columns with mobile padding. * **Disabling the left and right page padding forces the section to full width**, overriding the **Section width** setting. *** ### Customization ideas * Keep **Image ratio** on *Original* for lookbooks and process photography, and switch to a fixed ratio for catalogue-style grids that need to line up. * Use the **Page** setting to build a standalone gallery page: one page metafield, one section, no product involved. * Two columns on desktop with the original ratio gives a magazine spread. Five or six columns turn the same images into a contact sheet. * Set a tighter mobile spacing than desktop (the defaults are 8 px and 4 px) so the grid reads as one block on a phone. * Turn the zoom overlay to a custom colour with a background blur for a gallery that feels closer to a photo app than a storefront. *** ### Best practices * Define the metafield once, for every resource type you plan to use it on, before you add the section anywhere. Most empty galleries are a metafield that exists on Products but not on Pages. * Keep the files small. This is a second gallery on top of the product media, and it is downloaded on every visit. See [Image & video size recommendations](/docs/avante-themes/faq/performance/image-and-video-size-recommendations.md). * Fill the alt text on the files in the admin. It is used on the grid images and is the only description a screen reader gets. * Put the section below the product details. It is supporting material, not the buying decision. * Check a product that has no gallery on the live storefront as well as one that does. The section should simply vanish. *** ### Related * [Image with Hotspots](/docs/avante-themes/sections/media/image-with-hotspots.md) * [Image & video size recommendations](/docs/avante-themes/faq/performance/image-and-video-size-recommendations.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://staylime.com/docs/avante-themes/sections/media/image-grid.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.