Aspect Ratio

The Aspect Ratio component resizes its contents to match the desired ratio.

Introduction

Aspect Ratio is a wrapper component for quickly resizing content to conform to your preferred ratio of width to height. Media content like images can be stretched, resized, and cropped based on the CSS object-fit property.

Usage

After installation, you can start building with this component using the following basic elements:

import AspectRatio from '@mui/joy/AspectRatio';

export default function MyApp() {
  return <AspectRatio />;
}

Basics

The Aspect Ratio component wraps around the content that it resizes. The element to be resized must be the first direct child. The default ratio is 16/9.

Anatomy

The Aspect Ratio component is composed of a root <div> with a content <div> nested inside; the child component is given a data-first-child attribute for styling purposes:

<div class="JoyAspectRatio-root">
  <div class="JoyAspectRatio-content">
    <some-element data-first-child>
      This is how an Aspect Ratio component renders in the DOM.
    </some-element>
  </div>
</div>

Overriding the root slot

Use the component prop to override the root slot with a custom element. For example, the following code snippet replaces the default <div> with a <section>:

<AspectRatio component="section" />

Overriding interior slots

Use the components prop to override any interior slots in addition to the root:

<AspectRatio components={{ Content: 'article' }} />

Use the componentsProps prop to pass custom props to internal slots. The following code snippet applies a CSS class called my-content to the content slot:

<AspectRatio componentsProps={{ content: { className: 'my-content' } }} />

Customization

Variants

The Aspect Ratio component supports the four global variants: solid, soft (default), outlined, and plain.

Ratio

Use the ratio prop to change the aspect ratio, following the pattern height/width. For example, the demo below uses a ratio of 4/3, which is a common alternative to the default 16/9:

Object fit

When the content inside the Aspect Ratio component is an image or a video, you can use the objectFit prop to control how it's resized.

This prop gives you access to all of the values associated with the CSS object-fit property: cover (default), contain, fill, scaleDown, initial, inherit, and none.

Media placeholder

Use a <div>, or a Box component paired with an icon, as a fallback when there is no media content provided:

Minimum and maximum height

Use the minHeight and maxHeight props to set the lower and upper bound for the height of the content. This is useful when the Aspect Ratio component wraps dynamic-width content, as shown in the demo below:

Usage inside a flex row

When the Aspect Ratio component is a child of a flexbox row container, use flex-basis to set the ideal width of the content:

Usage with Next.js Image component

The Aspect Ratio component can be used with a Next.js Image component as a child. The Image should always include the layout="fill" property—otherwise it requires height and width values, which would defeat the purpose of the Aspect Ratio component.

import Image from 'next/image';
import AspectRatio from '@mui/joy/AspectRatio';
import mountains from '../public/mountains.jpg';

function App() {
  return (
    <AspectRatio variant="outlined" ratio="1" objectFit="cover">
      {/* only layout="fill" makes sense for using with AspectRatio */}
      <Image alt="Mountains" src={mountains} layout="fill" placeholder="blur" />
    </AspectRatio>
  );
}

Common examples

Mobile carousel

List stack

This is a simple illustration of how to use Aspect Ratio with list components: