Define Image Sizes

The file _config.json includes an optional key /imageSizes that specifies an array of image sizes. Each member of the list is a key-object pair that provides display information for an image—both within Brightspot and in published content. The key is used in imageSizeContexts as described in Define Image Size Context.

Tip

Before developing your own image sizes, check if they are already present in the styleguide hierarchy. Projects inherit image sizes starting from <project_root>/styleguide/_config.json, then from <project_root>/themes/<theme-dir>/_config.json.

Backend developers can also create image sizes without using _config.json. For details, see Creating Image Sizes and Using Image Sizes.

The following table lists the possible keys for an image size.

Key Description Type
width Width of rendered image in web page and generated image representation in Styleguide. Number
height Height of rendered image in web page and generated image representation in Styleguide. Number
previewWidth If width not set, width of image representation in Styleguide. Do not set previewWidth if width is set. Number
previewHeight If height not set, height of image representation in Styleguide. Do not set previewHeight if height is set. Number
maximumWidth Maximum width of image size. Aspect ratio will be preserved by the resize. If you define maximumWidth, you must also define previewWidth; otherwise, you will get an error. Number
maximumHeight Maximum height of image size. Aspect ratio will be preserved by the resize. If you define maximumHeight, you must also define previewHeight; otherwise, you will get an error. Number
srcsetDescriptors A list of image density or width descriptors to support different device screen resolutions. For more information, see srcSetDescriptors. Array of String
format Specifies the format in which an image is delivered to the client. For more information, see Image Format. String
group Heading under which an image size appears in the Image Editor. For more information, see Grouping Aspect Ratios in the Image Editor. String
displayName Customized label for an image size in the image editor. For more information, see Image Size Display Names. String
quality Specifies an image’s visual quality and compression level at run time. For more information, see Runtime Image Quality and Compression. Number

Naming Convention for Image Sizes

By default, Brightspot displays the image sizes in the image editor as they appear in a theme’s configuration file _config.json. As a best practice, define image sizes using the naming conventions in the following table.

Naming Convention Applies to…
<shape>-<size>-<width>x<height> Image size specifies both width and height.
auto-<size>-<width>xauto Image size specifies width, height scaled accordingly.
auto-<size>-autox<height> Image size specifies height, width scaled accordingly.

This format gives the editor a cue regarding the image’s size, orientation, and dimensions.

{
  "imageSizes": {
    "square-small-48x48": {},
    "landscape-large-800x100": {}
  }
}

The previous snippet defines two image sizes: square-small-48x48 and landscape-large-800x100, which Brightspot lists in the image editor.

../../_images/image-size-names.svg

As you create image sizes, ensure you do not duplicate names within the same configuration file _config.json or with any other configuration file you include using the key _include.

Fixed Image Size

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 1000x500 landscape image, with a 2:1 aspect ratio, the result is a 200x200 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 400x200. Brightspot then crops the width of the rendition to fit it into a 200x200 image size.

200x200 Square
../../_images/flower200x200-square.png

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

500x250 Landscape
../../_images/flower-native.png

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 1000x500 landscape image, the result is a 200x400 portrait image. Maintaining the 2:1 aspect ratio, Brightspot resizes the image to 800x400, which is the image rendition. To fit the image into a portrait-oriented size, Brightspot crops the width.

200x400 Portrait
../../_images/flower200x200-portrait.png

Maintaining Aspect Ratio

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 1000x500 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 400x200, which is the image rendition. Because the computed height does not exceed maximum height, the resulting image size is 400x200.

400x200
../../_images/flower-native.png

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

../../_images/image-sizes.png

If the image size defined in the above snippet is applied to a 500x500 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 200x200 to maintain aspect ratio. (In Styleguide, the image is represented with a 400x200 size.)

200x200
../../_images/desert.png

srcSetDescriptors

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.

Note

You cannot combine width descriptors and density descriptors.

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" />

Image Format

By default, Brightspot delivers images to a client in the format in which they are stored. For example, if you upload an image as a PNG, Brightspot delivers the image in the same format.

You can force Brightspot to deliver images of a given size in a given format—regardless of the format in which the image is stored. This feature is useful if you ingest or upload multiple images in one format, and want to deliver them to the browser in a different format. (If your travel editor took one thousand jaw-dropping photographs during a safari and uploaded them to Brightspot as PNGs, you can force Brightspot to convert the images to JPGs.)

The following table lists the available formats and their suggested uses.

Available Image Formats
Extension Name Suggested Use
png Portable Network Graphic Transparency.
gif Graphics Interchange Format Animation, small images with fewer than 256 colors.
jpg Joint Photographic Experts Group All other uses.

This feature is available if you configured DIMS as the image editor; for details, see Image Editor Configuration.

You can use any of the extensions in the table Available Image Formats with the format key inside the elements of an imageSizes array.

1
2
3
4
5
6
7
{
  "imageSizes": {
    "small": {
      "format": "jpg"
    }
  }
}

In the previous snippet, line 4 configures Brightspot to deliver as jpg all images whose context is small. (For an explanation of determining an image’s context, see Define Image Size Context.) Brightspot delivers the file by retrieving the original file and running it through a file converter as indicated in the following URL.

../../_images/target-online-image-format.svg

Referring to the previous illustration, Brightspot constructs an image’s src attribute from the original file’s name bowtie.png and an instruction to an online service for conversion to the jpg format. When the browser submits this request to the server, the image editor performs the conversion.

See also:

Image URLs

Grouping Aspect Ratios in the Image Editor

Brightspot’s image editor lists all of the image sizes available for the current theme, automatically grouping them by aspect ratio. The labels appearing in the list are elements of the imageSizes key in the theme’s configuration file _config.json.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "imageSizes": {
    "square-small-62x62": {
      "width": 62,
      "height": 62
    },
    "square-medium-84x84": {
      "width": 84,
      "height": 84
    },
    "square-large-765x765": {
      "width": 765,
      "height": 765
    },
     "landscape-small-54x50": {
      "width": 54,
      "height": 50
    }
  }
}

In the previous snippet, Brightspot identifies all of the image sizes with an aspect ratio of 1:1, and groups the corresponding labels in lines 3, 7, and 11 in the image editor. See the left image in the table Grouping Images by Aspect Ratio.

You can provide a more intuitive label for aspect-ratio groupings using the group key. With this key, Brightspot provides only one entry for each aspect ratio. You can also provide group labels that give editors a cue when the image size appears, such as Promo Size.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "imageSizes": {
    "square-small-62x62": {
      "width": 62,
      "height": 62,
      "group": "1:1"
    },
    "square-medium-84x84": {
      "width": 84,
      "height": 84,
      "group": "1:1"
    },
    "square-large-765x765": {
      "width": 765,
      "height": 765,
      "group": "1:1"
    },
     "landscape-small-54x50": {
      "width": 54,
      "height": 50,
      "group": "1.08:1"
    }
  }
}

In the previous snippet, Brightspot detects a heading 1:1 in lines 6, 11, and 16, and displays it only once, suppressing the individual names of the associated image sizes.

The following illustrations provide examples of the default grouping and a cleaner listing by group heading.

Grouping Images by Aspect Ratio
Default Group Headings Customized Group Headings
../../_images/image-grouping-default.svg ../../_images/image-grouping-custom.svg

See also:

Preparing an Image for Publication

Image Size Display Names

Brightspot’s image editor lists the image sizes as they appear in the theme’s configuration file _config.json.

{
  "imageSizes": {
    "square-small-62x62": {
      "width": 62,
      "height": 62
    },
    "square-medium-84x84": {
      "width": 84,
      "height": 84
    },
    "square-large-765x765": {
      "width": 765,
      "height": 765
    }
  }
}

In the previous snippet, Brightspot displays the names square-small-62x6, square-medium-84x84, and square-large-765x765. See the left image in the table Image-Size Labels.

You can provide a more intuitive name for each image size using the displayName key.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "imageSizes": {
    "square-large-765x765": {
      "width": 765,
      "height": 765,
      "displayName": "Huge Square"
    },
    "square-small-62x62": {
      "width": 62,
      "height": 62,
      "displayName": "Small Square"
    },
    "square-medium-84x84": {
      "width": 84,
      "height": 84,
      "displayName": "Medium Square"
    }
  }
}

In the previous snippet, lines 6, 11, and 16 provide custom names for the associated image sizes.

The following illustrations provide examples default and customized image-size names.

Image-Size Labels
Default Image-Size Names Customized Image-Size Names
../../_images/image-size-label-default.svg ../../_images/image-size-label-custom.svg

Runtime Image Quality and Compression

When delivering an image at runtime, Brightspot changes its quality level to a default of 90. (For detailed information about an image’s quality, see ImageMagick’s command-line option -quality.) You can force Brightspot to deliver images of a given size at a given quality—from 1 to 100. This feature is useful if you want to deliver a lower quality image placeholder (LQIP) before delivering the corresponding high-quality image.

This feature is available if you configured DIMS as the image editor; for details, see Image Editor Configuration.

{
  "imageSizes": {
    "square-large-2400x1800": {
      "width": 2400,
      "height": 1800,
      "quality": "10"
    }
  }
}

In the previous snippet, line 6 configures Brightspot to compress to quality 10 all images whose context is GrayscaleBackground. (For an explanation of determining an image’s context, see Define Image Size Context.) Brightspot delivers the file by retrieving the original file and running it through a file converter as indicated in the following URL.

../../_images/run-time-image-quality.svg

Referring to the previous illustration, Brightspot constructs an image’s src attribute from the original file’s name bowtie.png and an instruction to compress the image to level 10. When the browser submits this request to the server, the runtime image editor applies the indicated compression.