Defining image sizes
Defining image sizes at the theme level
Image sizes are defined in the configuration file (see Configuring a theme) of your theme. To define an image, you will at a minimum need to define the width
(or maximumWidth
) and height
(or maximumHeight
).
An example configuration file with a single image size definition would look like the following:
{ "imageSizes": { "MyImageSize": { "width": 100, "height": 100 } } }
Defining image sizes at the module level
You can define image sizes at the module level, overriding image sizes at the theme level. You can use all of the keys listed in the table Keys for image size in module-level data files except the following:
Key | Description | Type |
---|---|---|
previewWidth | This key is available at the module level only if the following are true:
| Number |
previewHeight | This key is available at the module level only if the following are true:
| Number |
The following snippet describes the height, width, and source set descriptors for a template Image.hbs
. These attributes override any of the contextual rendering settings in the theme's _config.json
.
{ "_template": "Image.hbs", "height": "900", "width": "1600", "srcsetDescriptors": [ "2x", "3x" ] }
Available properties
The following table lists the available properties when defining 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 | Number |
previewHeight | If | Number |
maximumWidth | Maximum width of image size. Aspect ratio will be preserved by the resize. If you define | Number |
maximumHeight | Maximum height of image size. Aspect ratio will be preserved by the resize. If you define | 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 images 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. | Number |
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.
{ "imageSizes": { "square-large-765x765": { "width": 765, "height": 765, "displayName": "Huge Square" 1 }, "square-small-62x62": { "width": 62, "height": 62, "displayName": "Small Square" 2 }, "square-medium-84x84": { "width": 84, "height": 84, "displayName": "Medium Square" 3 } } }
The following illustrations provide examples default and customized image-size names.
Figure 153. Default image-size names | Figure 154. Customized image-size names |
Grouping images in the image editor
Editors can set a focus point on images. If your theme has many image sizes and orientations, the editors may want to place the focus point in different locations.
Figure 155. Focus point on portrait orientation | Figure 156. Focus point on square orientation |
Referring to the previous illustrations, the focus point is in the bottom-right quadrant of the portrait image; in comparison, the focus point is in the top-left quadrant of the square image.
If you have multiple images with the same aspect ratio, the focus point is always in the same place, scaled for the image size. For example, if an image is 1000 × 500 with a focus point at (100, 250), and another image is 2000 × 1000, the focus point for the second image is scaled to (200, 500). This implies that an editor can set a focus point once for all images with the same aspect ratio, and Brightspot scales the focus point when performing crops.
You can group images into the same or similar aspect ratio using the group
key under imageSizes
.
{ "imageSizes": { "80x80": { "width": 80, "height": 80, "group": "square" 1 }, "100x100": { "width": 100, "height": 100, "group": "square" }, "150x100": { "width": 150, "height": 100, "group": "landscape" 2 } }
Groups images under a label Square in the image editor. | |
Groups images under a label Landscape in the image editor. |
When detecting at least one group key in the theme, Brightspot displays a selection field containing all of the groups.
When an editor selects one of the groups and sets a focus point, Brightspot applies and scales the focus point to all associated image sizes.
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.
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.
{ "imageSizes": { "small": { "format": "jpg" 1 } } }
Delivers as |
Brightspot delivers the file by retrieving the original file and running it through a file converter as indicated in the following URL.
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.
Examples
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 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.

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.

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.

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

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

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