Skip to contentSkip to navigationSkip to topbar
Paste assistant Assistant
Figma
Star

Aspect Ratio

Version 10.1.0GithubStorybook
Component preview theme
<Box
padding="space30"
maxWidth="size60"
borderColor="colorBorderWeak"
borderStyle="solid"
borderWidth="borderWidth10"
>
<AspectRatio ratio="16:9">
<iframe width="560" height="315" src="https://www.youtube.com/embed/UBFDdTIYZ6Q" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</AspectRatio>
</Box>

Guidelines

Guidelines page anchor

About Aspect Ratio

About Aspect Ratio page anchor

The Aspect Ratio layout component dynamically modifies the height of an element based on its current width to match a width-to-height ratio. For example, a 4:3 ratio would make an element with a width of 400px have a height of 300px. This updates in real time when you resize the screen.

Aspect Ratio must contain exactly one child element. The child element should be sized fully to the Aspect Ratio bounding box so that it resizes correctly. One way of achieving this is using an absolutely positioned Box primitive.

Be considerate of smaller devices when using this component. If necessary, you can modify the aspect ratio property at certain media query breakpoints.

When to use Aspect Ratio

When to use Aspect Ratio page anchor

Aspect Ratio can be used to embed images and videos.

Use Aspect Ratio to make sure images and videos are scaled correctly on displays of various sizes. For example, you can use Aspect Ratio when a customer needs to see a preview of an uploaded document.

Component preview theme
<Box
padding="space30"
maxWidth="size60"
borderColor="colorBorderWeak"
borderStyle="solid"
borderWidth="borderWidth10"
>
<AspectRatio ratio="16:9">
<iframe width="560" height="315" src="https://www.youtube.com/embed/UBFDdTIYZ6Q" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</AspectRatio>
</Box>

Aspect Ratio can also be used to embed components, or other HTML elements that needs to be set to a specific width-to-height ratio. A component or other HTML element use case is the need to align an HTML element with an image in two columns.

Component preview theme
<Box
padding="space30"
maxWidth="size50"
borderColor="colorBorderWeak"
borderStyle="solid"
borderWidth="borderWidth10"
>
<AspectRatio ratio="4:3">
<Box position="absolute" top={0} right={0} bottom={0} left={0} display="flex" alignItems="center" justifyContent="center">
<Anchor href="https://org2.salsalabs.com/o/6857/p/salsa/donation/common/public/?donate_page_KEY=15780">Donate to the NAACP Legal Defense Fund</Anchor>
</Box>
</AspectRatio>
</Box>

Another use case is for color swatches on a documentation site. These color swatches could be a specific height/width div that need to resize on specific devices. Aspect Ratio will allow the color swatches to resize correctly based on a ratio.

Component preview theme
<Box
padding="space30"
maxWidth="size50"
borderColor="colorBorderWeak"
borderStyle="solid"
borderWidth="borderWidth10"
>
<AspectRatio ratio="4:3">
<Box position="absolute" top={0} right={0} bottom={0} left={0} backgroundColor="colorBackgroundBrand" />
</AspectRatio>
</Box>
Do

Use for an image or embedded video, and have it resize at a specific ratio.

Don't

Don’t use with fixed size (width & height) elements, as those will not adhere to the width-to-height ratio.

Do

Use to embed a component or other HTML element.

Don't

Don’t use without any child elements, because this is only a container element.