Support and Documentation

Setting both width and height dimensions results in a fixed image size. A fixed image size may result in cropping if the image size does not reflect the aspect ratio of the original image.

The following image-size snippet defines a square shape, with equal width and height dimensions.

{
  "imageSizes": {
    "square-medium-200x200": {
      "width": 200,
      "height": 200
    }
  }
}

If the snippet is applied to a 1000×500 landscape image, with a 2:1 aspect ratio, the result is a 200×200 square image that is cropped because the image size does not reflect the aspect ratio of the original image. Brightspot first creates an image rendition that maintains the aspect ratio of the landscape image. In this example, the ratio is 2:1, so Brightspot resizes the image to 400×200. Brightspot then crops the width of the rendition to fit it into a 200×200 image size.

Figure 226. 200×200 square

The next image-size snippet defines a landscape shape, with the width greater than the height.

{
  "imageSizes": {
    "landscape-large-500x250": {
      "width": 500,
      "height": 250
    }
  }
}

If the snippet is applied to a 1000×500 landscape image, the result is a scaled-down landscape image. The image is also uncropped because the image size reflects the aspect ratio of the original image, 2:1.

Figure 227. 500×250 landscape

The next image-size snippet defines a portrait image, with the height greater than the width.

{
  "imageSizes": {
    "portrait-medium-200x400": {
      "width": 200,
      "height": 400
    }
  }
}

If the snippet is applied to a 1000×500 landscape image, the result is a 200×400 portrait image. Maintaining the 2:1 aspect ratio, Brightspot resizes the image to 800×400, which is the image rendition. To fit the image into a portrait-oriented size, Brightspot crops the width.

Figure 228. 200×400 portrait

As an alternative to a fixed image size, you can have Brightspot calculate the size by specifying only one image dimension, width or height, or by using width or height in conjunction with a maximumHeight or a maximumWidth key. As in a fixed image size, Brightspot creates an image rendition based on the aspect ratio of the image, but Brightspot does not crop the rendition to fit a fixed size. In essence, the image rendition dimensions determine the image size.

The maximumWidth and maximumHeight keys can restrict the width or height of an image while preserving the aspect ratio. For example, say that you have a 1000×500 landscape image, with a 2:1 aspect ratio. The following snippet specifies that the resulting image size not exceed a height of 200.

{
  "imageSizes": {
    "auto-small-400xauto": {
      "width": 400,
      "maximumHeight": 200,
      "previewHeight": 200
    }
  }
}

Maintaining the 2:1 aspect ratio, Brightspot resizes the image to 400×200, which is the image rendition. Because the computed height does not exceed maximum height, the resulting image size is 400×200.

Figure 229. 400×200

Using the width and previewHeight values, Styleguide generates a 400×200 image representation.

If the image size defined in the above snippet is applied to a 500×500 square image, with a 1:1 aspect ratio, the resulting image size is different. Maintaining the 1:1 aspect ratio of the image, Brightspot initially computes a height of 400, which exceeds the maximum height. Brightspot then resizes the image to 200×200 to maintain aspect ratio. (In Styleguide, the image is represented with a 400×200 size.)

Figure 230. 200×200

To accommodate image display on devices with different resolutions, the srcsetDescriptors key specifies density descriptors or width descriptors. This key provides support for the HTML srcset attribute. Brightspot generates images of different densities or widths, and the browser determines the applicable image based on the device screen resolution or viewport size.

Use density descriptors for images that should maintain the same width across devices, but should vary by resolution to support displays with different pixel densities. For example, the following image snippet specifies a density array of 2x and 3x.

{
  "imageSizes": {
    "landscape-small-300x200": {
      "width": 300,
      "height": 200,
      "srcsetDescriptors": [
             "2x",
             "3x"
       ]
    }
  }
}

This results in the following srcset attribute in the HTML image tag:

<img src="src.png" srcset="src-2.png 2x, src-3.png 3x" />

Use width descriptors for images that are likely to change in width, especially in responsive designs. With width descriptors, images vary in width based on the size of the viewport.

For example, the following image snippet specifies a width array of "1000w" and "2000w".

{
  "imageSizes": {
    "auto-large-autox1000": {
      "maximumWidth": 2000,
      "previewWidth": 2000,
      "height": 1000,
      "srcsetDescriptors": [
             "1000w",
             "2000w"
       ]
    }
  }
}

This results in the following srcset attribute in the HTML image tag. If the viewport is 1000 pixels wide or smaller, the image will be 100% of the viewport width, and the browser will use the src-1000.png image. If the viewport is wider than 1000 pixels, the browser will use the src-2000.png image.

<img src="src.png" srcset="src-1000.png 1000w, src-2000.png 2000w" sizes="(max-width: 1000px) 100vw, 2000px" />