You appear to be using an unsupported browser, and it may not be able to display this site properly. You may wish to upgrade your browser.

Aspect box

An aspect box crops images to a particular aspect ratio.
A wide photograph of some thistles with a one-to-one square box overlaid on top of it to show how the image would be cropped. The resulting square crop of the thistles photograph is shown next to it.

Sample HTML

<div class="ds_aspect-box  ds_aspect-box--square">
 <img alt="Thistle flowers in a field" class="ds_aspect-box__inner">

About this component

Aspect box is a component used to constrain an image to a particular aspect ratio. It will crop 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

When it's not possible to use exactly-sized images, the aspect box component 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.

Related components


Aspect box uses a CSS property not supported in old browsers. 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. Assistive technologies will still announce the text.

The user must have JavaScript enabled in their browser for the fallback to work.


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
Back to top