Thumbnails

This guide describes how to request for a thumbnail and how the thumbnails are generated.

Thumbnails sizes and formats

Thumbnails are available on the following fields:

User.avatar
OrderLine.thumbnail
Product.thumbnail
Collection.backgroundImage
Category.backgroundImage
ProductMedia.url
ProductImage.url
AppBrandLogo.default
AppManifestBrandLogo.default

You can specify the size, sizeRounding, and format of a thumbnail.

Size defines the longest dimension of the thumbnail in pixels. Thumbnails are generated only in the following sizes: 32, 64, 128, 256, 512, 1024, 2048, 4096. You may pass any integer as size. If it is not one of the supported sizes, Saleor matches it to one of them using the sizeRounding argument.

If omitted, 4096 is used as a default value. Set to 0 it will allow to get original size thumbnail and can potentially resolve an issue when thumbnails are not generating because they weren’t resized.

Size Rounding

Added in Saleor 3.23.

sizeRounding accepts the following values:

UP: the smallest supported size that is not smaller than the requested one. For example, 1500 returns an image that is at most 2048 pixels on its longest side. Sizes above 4096 return 4096.
NEAREST: the closest supported size. It may be smaller than the requested one: 1500 is closer to 1024 than to 2048, so Saleor returns an image that is at most 1024 pixels on its longest side. When the value is exactly halfway between two sizes (e.g. 768), the smaller size is used.

Requested size	Returned size with `UP`	Returned size with `NEAREST`
1–32	32	32
33–48	64	32
49–64	64	64
65–96	128	64
97–128	128	128
129–192	256	128
193–256	256	256
257–384	512	256
385–512	512	512
513–768	1024	512
769–1024	1024	1024
1025–1536	2048	1024
1537–2048	2048	2048
2049–3072	4096	2048
3073 and above	4096	4096

The default depends on the Saleor version:

Saleor 3.24 and newer: UP. Pass sizeRounding: NEAREST to restore the previous behavior.
Saleor 3.23: NEAREST. Pass sizeRounding: UP to opt in to rounding up.

Passing null uses the default. Product thumbnails in email notifications follow the same default.

Thumbnails are never upscaled: if the original image is smaller than the selected size, the image is returned at its original dimensions.

Format

Supported formats:

ORIGINAL: the format the image was uploaded in.
WEBP: WebP format.
AVIF: AVIF format.

If omitted, ORIGINAL is used as a default value.

Generating the thumbnails

The thumbnails are generated on demand. When a client requests the thumbnail with the given size and format for the first time, a proxy URL is returned. When the proxy URL is accessed, the requested thumbnail is created and the client is redirected. Future requests return the thumbnail’s URL directly.

In Saleor Cloud media files (e.g. product images) are publicly available on the Internet. Media files are served by CDN (Content Delivery Network — Amazon Cloudfront). CDN may cache media files for up to 604800 seconds (7 days). This means media files uploaded to Saleor Cloud may still be available under its URL for up to 7 days after they’ve been deleted from Saleor Cloud.

Example

Here is an example query for the category’s background image with a size of 100px in WebP format:

query {
  category(id: "Q2F0ZWdvcnk6MjU=") {
    name
    backgroundImage(size: 100, format: WEBP) {
      url
      alt
    }
  }
}

The query runs for the first time, and as a result, the response contains a proxy URL:

{
  "data": {
    "category": {
      "name": "Accessories",
      "backgroundImage": {
        "url": "https://localhost:8000/thumbnail/Q2F0ZWdvcnk6MjU=/128/webp/",
        "alt": ""
      }
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 1,
      "maximumAvailable": 50000
    }
  }
}

After opening the link, the thumbnail with the size of 128, and the format of WEBP is generated. The resolution is 128: it is both the closest supported size and the smallest one not smaller than 100, so UP and NEAREST return the same size.

The next time we run the query, we receive the URL to the actual thumbnail.

{
  "data": {
    "category": {
      "name": "Accessories",
      "backgroundImage": {
        "url": "http://localhost:8000/media/thumbnails/category-backgrounds/20210809_181533_2240b122_thumbnail_128.webp",
        "alt": ""
      }
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 1,
      "maximumAvailable": 50000
    }
  }
}