Image

Image objects appear in several places: product.images, product.featured_image, collection.image, and inside variant and section settings. They all share the same set of properties.

Properties

Displaying images

The simplest way to show an image is with the image_tag filter. It builds a full <img> tag with lazy loading and responsive sizes:

{{ product.featured_image | image_tag }}

For more control, use the img_url filter to get a sized URL:

<img
  src="{{ image | img_url: '800x' }}"
  alt="{{ image.alt }}"
  width="{{ image.width }}"
  height="{{ image.height }}"
/>

Setting width and height on the <img> tag prevents layout shift while the image loads.

Alt text

Good alt text helps with both SEO and screen readers. Check for it and provide a fallback:

{% assign alt = image.alt | default: product.title %}
<img src="{{ image | img_url: '400x400' }}" alt="{{ alt }}" />

Looping over product images

Show all images in a product gallery:

<div class="gallery">
  {% for image in product.images %}
    <figure>
      <img src="{{ image | img_url: '600x' }}" alt="{{ image.alt }}" />
      {% if image.alt != blank %}
        <figcaption>{{ image.alt }}</figcaption>
      {% endif %}
    </figure>
  {% endfor %}
</div>

Checking for images

Always check that an image exists before using it. Some products and collections may not have images:

{% if product.featured_image %}
  {{ product.featured_image | image_tag }}
{% else %}
  <img src="{{ 'placeholder.png' | asset_url }}" alt="No image" />
{% endif %}

Aspect ratio

Calculate the aspect ratio from the width and height. This is useful for CSS padding-based aspect ratio boxes:

{% assign ratio = image.height | times: 100.0 | divided_by: image.width %}
<div style="padding-bottom: {{ ratio }}%">
  <img src="{{ image | img_url: '800x' }}" alt="{{ image.alt }}" />
</div>

Common sizes

Here are typical sizes used across a theme:

The CDN resizes the image on the fly. You always upload the largest version and let the filters handle the rest.