跳转到内容

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 accomodate 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>

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>

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.

A beautiful landscape.
<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>

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>

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>

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


px

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

Night view

4.21M views

Lake view

Lake view

4.74M views

Mountain view

Mountain view

3.98M views

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

  • Night view

    Night view

    4.21M views

  • Lake view

    Lake view

    4.74M views

  • Mountain view

    Mountain view

    3.98M views