Aspect box

An aspect box crops images to a particular aspect ratio.

Sample HTML

<div class="ds_aspect-box  ds_aspect-box--square">
    <img alt="Thistle flowers in a field" class="ds_aspect-box__inner" src="/assets/images/graphics/thistles.jpg" />

About this component

Aspect box is a component used to constrain an image to a particular aspect ratio, cropping the image if necessary. It supports common aspect ratios of:

  • 1:1 (square)
  • 4:3 (standard fullscreen)
  • 16:9 (standard widescreen)
  • 21:9 (anamorphic widescreen)

Why we use this component

While it is preferable to use exactly-sized images for best performance, doing so is not always practical. Using the aspect box component to crop incorrectly-sized images helps with art direction and maintaining a uniform appearance, for example in a grid of image cards where differently-sized images would make the page appear jumbled.


Aspect box uses a CSS property not supported in old browsers, and we address this using a fallback which restructures the HTML. The fallback clones the alt attribute of the image as an ARIA label on the replacement HTML so that assistive technologies will still announce the text.

The fallback requires JavaScript to be enabled in the user’s browser.


Aspect boxes use an aspect ratio of 16:9 (standard widescreen) by default. To specify a different aspect ratio, there are 3 modifier classes you can use.

Aspect ratio Modifier class
1:1 ds_aspect-box--square
4:3 ds_aspect-box--43
21:9 ds_aspect-box--219

Feedback, help or support

If you need any help or want to give any feedback you can e-mail us at:

Back to top