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.

Basics

<span class="token keyword">import</span> AspectRatio <span class="token keyword">from</span> <span class="token string">'@mui/joy/AspectRatio'</span><span class="token punctuation">;</span>

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.

16/9

<AspectRatio sx={{ width: 300 }}>
  <Typography level="h2" component="div">
    16/9
  </Typography>
</AspectRatio>

<AspectRatio sx={{ width: 300 }}>
  <Typography level="h2" component="div">
    16/9
  </Typography>
</AspectRatio>

Press Enter to start editing

Customization

Variants

The Aspect Ratio component supports Joy UI's four global variants: solid, soft (default), outlined, and plain.

Solid

Soft

Outlined

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:

4/3

<AspectRatio
  variant="outlined"
  ratio="4/3"
  sx={{
    width: 300,
    bgcolor: 'background.level2',
    borderRadius: 'md',
  }}
>
  <Typography level="h2" component="div">
    4/3
  </Typography>
</AspectRatio>

<AspectRatio
  variant="outlined"
  ratio="4/3"
  sx={{
    width: 300,
    bgcolor: 'background.level2',
    borderRadius: 'md',
  }}
>
  <Typography level="h2" component="div">
    4/3
  </Typography>
</AspectRatio>

Press Enter to start editing

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.

<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 a Box component paired with an icon, as a 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>
  <div>
    <Typography>Title</Typography>
    <Typography level="body2">Description of the card.</Typography>
  </div>
</Card>

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

Press Enter to start editing

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:

<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

Using 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:

Yosemite National Park

California, USA

flexBasis

Using with Next.js Image

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.

<span class="token keyword">import</span> Image <span class="token keyword">from</span> <span class="token string">'next/image'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> AspectRatio <span class="token keyword">from</span> <span class="token string">'@mui/joy/AspectRatio'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> mountains <span class="token keyword">from</span> <span class="token string">'../public/mountains.jpg'</span><span class="token punctuation">;</span>

<span class="token keyword">function</span> <span class="token function">App</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">return</span> <span class="token punctuation">(</span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">AspectRatio</span></span> <span class="token attr-name">variant</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>outlined<span class="token punctuation">"</span></span> <span class="token attr-name">ratio</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>1<span class="token punctuation">"</span></span> <span class="token attr-name">objectFit</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>cover<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
      <span class="token punctuation">{</span><span class="token comment">/* only layout="fill" makes sense for using with AspectRatio */</span><span class="token punctuation">}</span>
      <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Image</span></span> <span class="token attr-name">alt</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>Mountains<span class="token punctuation">"</span></span> <span class="token attr-name">src</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span>mountains<span class="token punctuation">}</span></span> <span class="token attr-name">layout</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>fill<span class="token punctuation">"</span></span> <span class="token attr-name">placeholder</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>blur<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">AspectRatio</span></span><span class="token punctuation">></span></span>
  <span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

Using with an icon

The Aspect Ratio component can be a handy tool for creating a square container for an icon.

The example below show

Common examples

Mobile carousel

Night view

4.21M views

Lake view

4.74M views

Mountain view

3.98M views

List stack

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

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

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:

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>div</span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>MuiAspectRatio-root<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>div</span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>MuiAspectRatio-content<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>some-element</span> <span class="token attr-name">data-first-child</span><span class="token punctuation">></span></span>
      <span class="token comment">&lt;!-- Aspect Ratio contents --></span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>some-element</span><span class="token punctuation">></span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>div</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>div</span><span class="token punctuation">></span></span>

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

<AspectRatio />