In Shopify themes, the image_tag filter is a Liquid filter that generates a complete HTML <img> element from an image URL — including the attributes that make an image responsive, accessible, and fast to load. Paired with the image_url filter, it is the modern, recommended way to render images in an Online Store 2.0 theme. This guide covers what the filter does, how to use it, and how to handle the common problems that come up.

Liquid and Shopify's image CDN, briefly

Liquid is the templating language Shopify themes are built on. It pulls data — products, collections, settings — into HTML at render time, so the same template can display different content on every page. Image filters are part of that system: they turn an image reference into markup at render.

Every image uploaded to Shopify is served through Shopify's image CDN, which delivers files from servers close to each visitor and can resize and reformat images on the fly. That is why passing a width to image_url returns a correctly sized file rather than the full-resolution original — the CDN generates the requested size on request.

Using the image_tag filter

At its simplest, image_tag takes an image URL and outputs an <img> element. It is almost always combined with image_url, which produces the URL at a given size:

{{ product.featured_image | image_url: width: 600 | image_tag }}

That single line outputs an <img> tag with a correctly sized src, plus width and height attributes inferred from the image — which helps prevent layout shift as the page loads. Any additional attributes can be passed as arguments to the filter.

Alt text

The alt attribute describes an image for screen readers and search engines and should be set on meaningful images. Shopify pulls it from the image's own alt field automatically, or it can be set explicitly:

{{ product.featured_image | image_url: width: 600 | image_tag: alt: product.title }}

Responsive images with widths and srcset

A responsive image lets the browser download the size it actually needs for the visitor's screen, rather than one large file for everyone. The image_tag filter builds the srcset attribute automatically from a list of widths:

{{ product.featured_image | image_url: width: 1200 | image_tag: widths: '300, 600, 900, 1200' }}

Here the image_url width sets the largest size, and widths lists the candidate widths for the srcset. The browser then picks the most appropriate file for the device's screen and resolution.

The sizes attribute

The sizes attribute tells the browser how wide the image will actually display at different viewport widths, so it can choose from srcset accurately. Without it, the browser assumes the image spans the full viewport:

{{ product.featured_image | image_url: width: 1200 | image_tag: widths: '300, 600, 900, 1200', sizes: '(min-width: 750px) 600px, 100vw' }}

This says the image displays at 600px on viewports 750px and wider, and full-width below that.

Common attributes worth setting

loading: set loading: 'lazy' on below-the-fold images so they load only as the visitor scrolls to them, and leave the main hero or first product image eager so it appears immediately.
width and height: explicit dimensions reserve space and reduce cumulative layout shift, a factor in Core Web Vitals.
class: pass a CSS class to style or size the image from the theme's stylesheet.

{{ product.featured_image | image_url: width: 800 | image_tag: loading: 'lazy', class: 'product-image', alt: product.title }}

Art direction with the picture element

Sometimes different screen sizes need genuinely different crops — a wide banner on desktop, a tighter square on mobile. That is art direction, and it calls for a <picture> element with multiple <source> entries rather than a single <img>. Each source points at a differently sized or cropped image via image_url, with the <img> as the fallback. The image_tag filter handles the common responsive case; reach for <picture> only when the crop itself needs to change.

Legacy filters to retire

Older themes and tutorials use img_url and img_tag. These still function but are deprecated in favor of image_url and image_tag, which produce cleaner, more capable markup. When updating a theme, replacing the legacy filters is worthwhile — the newer filters handle srcset, dimensions, and lazy loading more cleanly.

Common issues and fixes

Missing width and height

Images without width and height attributes cause the page to jump as they load. The image_tag filter adds dimensions automatically, so switching from a hand-written <img> to the filter usually resolves this. On markup that must stay manual, add explicit width and height attributes matching the image's aspect ratio.

Placeholder images

When a product has no image, a placeholder keeps layouts intact. Shopify provides placeholder_svg_tag for this, typically inside a conditional that checks whether an image exists before falling back to the placeholder.

Oversized files on mobile

If mobile devices are downloading desktop-sized images, the fix is almost always a missing or inaccurate sizes attribute — the browser is guessing full-width. Setting sizes to reflect the real display width lets it pick a smaller file.

Image handling is one piece of on-page performance and SEO; descriptive alt text and correct sizing also feed search visibility, covered in the guide to SEO optimization on a Shopify site.

Frequently asked questions

What is the image_tag filter in Shopify?

It is a Liquid filter that generates a complete HTML <img> element from an image URL, including dimensions and, when given a list of widths, a responsive srcset. It is used with the image_url filter, which produces the sized image URL.

What is the difference between image_tag and img_tag?

They do similar jobs, but img_tag (with img_url) is the older, deprecated pair, while image_tag (with image_url) is the current, recommended one. New and updated themes should use image_tag.

How do you make Shopify images responsive?

Pass a list of sizes to the widths argument of image_tag to build a srcset, and set a sizes attribute that reflects how wide the image actually displays. The browser then downloads the most appropriate size for each device.

How do you add alt text to a Shopify image?

Set the alt field on the image in the admin, which the image_tag filter uses automatically, or pass an explicit alt argument to the filter. Alt text should describe meaningful images and can be left empty for purely decorative ones.

The bottom line

The image_tag filter, used with image_url, is the cleanest way to render theme images: it produces responsive, correctly sized, accessible markup with far less hand-written HTML. Setting sensible widths, a realistic sizes attribute, lazy loading below the fold, and good alt text covers most of what makes store images fast and search-friendly.

First Pier is an ecommerce agency in Portland, Maine that builds and optimizes Shopify and Shopify Plus storefronts. For help with theme development or store performance, get in touch.