Skip to main content

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

Size​

Size defines the longest dimension of the thumbnail in pixels. You may pass any integer as size, Saleor will use the closest value from the following list: 32, 64, 128, 256, 512, 1024, 2048, 4096.

For example, if you pass 55 as size, Saleor will find the closest supported size, 64, and return an image that is at most 64 by 64 pixels.

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.

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.

note

Proxy URL will be constructed using a domain that Saleor is set to run on. This can be changed using shopDomainUpdate mutation.

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