Skip to main content

Thumbnails

note

Thumbnails with the configurable format were introduced in Saleor 3.6.

Introduction​

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 models and fields:

  • User.avatar
  • OrderLine.thumbnail
  • Product.thumbnail
  • Collection.background_image
  • Category.background_image
  • ProductMedia.url
  • ProductImage.url

You can specify the size and format of a thumbnail. You may pass any integer as size, but we will resolve it to the closest value from the following list: [32, 64, 128, 256, 512, 1024, 2048, 4096]. For example: when you pass "55", we resolve it to "64".

Currently, WebP is the only supported value for format. Both size and format fields are optional, but when you decide to provide format, the size becomes required as well. If you don't specify these or pass only one, the original image attributes will be used.

caution

You may have encountered a problem with the WebP content type recognition. Currently, there is an issue in Python with validation of the content type of WebP files, but it should be fixed in version 3.11. Until then, to fix the problem, extend one of mime.types files with the image/webp.

Generating the thumbnails​

The thumbnails are generated on-demand. When the user requests the thumbnail with the given size and format for the first time, the proxy URL is returned. When the proxy URL is opened, the requested thumbnail is created and the user gets the requested image. In case of a second and further request for the same thumbnail, the previously created thumbnail's URL is returned.

Example​

Here is an example query for the category's background image of size = "100" and format = "WebP":

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 proxy URL:

{
  "data": {
    "category": {
      "name": "Accessories",
      "backgroundImage": {
        "url": "http://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 equal to 128 as this is the closest available size to the provided value.

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
    }
  }
}