Aspect ratio

The aspect ratio component shapes the content with the specified ratio.

Introduction

AspectRatio is a wrapper component that allows you to rapidly control its content aspect ratio. Its default implementation combines height: 0px with percentage padding-bottom to properly accommodate the content.

Component

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 />;
}

Basic usage

The default aspect ratio is 16/9. Make sure that the content you want to fit the aspect ratio is its first direct child.

16 : 9

<Sheet
  variant="outlined"
  sx={{ width: 300, borderRadius: 'md', overflow: 'auto' }}
>
  <AspectRatio>
    <Typography level="h2" component="div">
      16 : 9
    </Typography>
  </AspectRatio>
</Sheet>
<Sheet
  variant="outlined"
  sx={{ width: 300, borderRadius: 'md', overflow: 'auto' }}
>
  <AspectRatio>
    <Typography level="h2" component="div">
      16 : 9
    </Typography>
  </AspectRatio>
</Sheet>

Press Enter to start editing

Variants

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

Plain

Outlined

Soft

solid

Ratio

Use the ratio prop to change the aspect ratio. The value will used by the CSS calc() function.

4 : 3

<Sheet
  variant="outlined"
  sx={{ width: 300, borderRadius: 'md', overflow: 'auto' }}
>
  <AspectRatio ratio="4/3">
    <Typography level="h2" component="div">
      4 : 3
    </Typography>
  </AspectRatio>
</Sheet>
<Sheet
  variant="outlined"
  sx={{ width: 300, borderRadius: 'md', overflow: 'auto' }}
>
  <AspectRatio ratio="4/3">
    <Typography level="h2" component="div">
      4 : 3
    </Typography>
  </AspectRatio>
</Sheet>

Press Enter to start editing

Media

When using media elements as first child of the aspect ratio component, use the objectFit prop to control how it should be resized. It comes with object-fit: cover set by default.

<AspectRatio objectFit="contain">
  <img
    src="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800"
    srcSet="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800&dpr=2 2x"
    alt="A beautiful landscape."
  />
</AspectRatio>
<AspectRatio objectFit="contain">
  <img
    src="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800"
    srcSet="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800&dpr=2 2x"
    alt="A beautiful landscape."
  />
</AspectRatio>

Press Enter to start editing

Media placeholder

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

Title

Description of the card.

<Card variant="outlined" sx={{ width: 300 }}>
  <AspectRatio>
    <div>
      <ImageIcon fontSize="xl5" sx={{ color: 'text.tertiary' }} />
    </div>
  </AspectRatio>
  <Typography mt={2}>Title</Typography>
  <Typography level="body2">Description of the card.</Typography>
</Card>
<Card variant="outlined" sx={{ width: 300 }}>
  <AspectRatio>
    <div>
      <ImageIcon fontSize="xl5" sx={{ color: 'text.tertiary' }} />
    </div>
  </AspectRatio>
  <Typography mt={2}>Title</Typography>
  <Typography level="body2">Description of the card.</Typography>
</Card>

Press Enter to start editing

Controlling the height

Use minHeight and maxHeight to set the lower and upper bound of the component's height. This is useful when the aspect ratio is used in a component that has dynamic width.

<AspectRatio minHeight={120} maxHeight={200}>
  <img
    src="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800"
    srcSet="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800&dpr=2 2x"
    alt=""
  />
</AspectRatio>
<AspectRatio minHeight={120} maxHeight={200}>
  <img
    src="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800"
    srcSet="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800&dpr=2 2x"
    alt=""
  />
</AspectRatio>

Press Enter to start editing

Inside a flex row

When the aspect ratio component is placed as a child of a flexbox row container, use flex-basis to set the ideal width of the aspect ratio.

Yosemite National Park

California, USA

flexBasis

Integration with Next.js Image component

The AspectRatio component can also be used with a Next.js Image component as child.

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

In designs such as this one, make sure to assign a minWidth value to prevent the aspect ratio component from shrinking.

Night view

4.21M views

Lake view

4.74M views

Mountain view

3.98M views

List stack

This is a simple illustration of composing aspect ratio with list components.

Night view
4.21M views
Lake view
4.74M views
Mountain view
3.98M views