Aspect Ratio

Keep a box at a fixed proportion for images, video and embeds.

New

1import { AspectRatio } from '@/components/ui/aspect-ratio';
2
3export function Default() {
4  return (
5    <div className="w-full max-w-md">
6      <AspectRatio ratio={16 / 9} className="rounded-xl">
7        <img src="https://picsum.photos/seed/aspect/960/540" alt="Office at golden hour" />
8      </AspectRatio>
9    </div>
10  );
11}

Installation

Copy and paste the following code into your project.

1import React from 'react';
2import { cn } from '../lib/cn';
3
4type AspectRatioOwnProps<E extends React.ElementType> = {
5  as?: E;
6  ratio?: number;
7  className?: string;
8  style?: React.CSSProperties;
9};
10
11type AspectRatioProps<E extends React.ElementType = 'div'> = AspectRatioOwnProps<E> &
12  Omit<React.ComponentPropsWithRef<E>, keyof AspectRatioOwnProps<E>>;
13
14const AspectRatio = <E extends React.ElementType = 'div'>({
15  as,
16  ratio = 16 / 9,
17  className,
18  style,
19  ...props
20}: AspectRatioProps<E>) => {
21  const Component: React.ElementType = as ?? 'div';
22  return (
23    <Component
24      data-slot="aspect-ratio"
25      style={{ aspectRatio: String(ratio), ...style }}
26      className={cn(
27        'relative w-full overflow-hidden [&>iframe]:absolute [&>iframe]:inset-0 [&>iframe]:size-full [&>img]:size-full [&>img]:object-cover [&>video]:size-full [&>video]:object-cover',
28        className,
29      )}
30      {...props}
31    />
32  );
33};
34
35AspectRatio.displayName = 'AspectRatio';
36
37export { AspectRatio };
38export type { AspectRatioProps };

Update the import paths to match your project structure.

Anatomy

1import { AspectRatio } from '@/components/ui/aspect-ratio';

1<AspectRatio ratio={16 / 9} className="rounded-lg">
2  <img src="/cover.jpg" alt="Cover" />
3</AspectRatio>

The box takes the full width of its parent and derives its height from ratio through the CSS aspect-ratio property, so nothing jumps while the media loads. A direct img or video child fills the box with object-cover, and an iframe is stretched to cover it.

Examples

Default

1import { AspectRatio } from '@/components/ui/aspect-ratio';
2
3export function Default() {
4  return (
5    <div className="w-full max-w-md">
6      <AspectRatio ratio={16 / 9} className="rounded-xl">
7        <img src="https://picsum.photos/seed/aspect/960/540" alt="Office at golden hour" />
8      </AspectRatio>
9    </div>
10  );
11}

Ratios

Any number works: 1, 4 / 3, 3 / 4, 21 / 9.

1 / 1

4 / 3

3 / 4

21 / 9

1import { AspectRatio } from '@/components/ui/aspect-ratio';
2
3const ratios = [
4  { label: '1 / 1', value: 1 },
5  { label: '4 / 3', value: 4 / 3 },
6  { label: '3 / 4', value: 3 / 4 },
7  { label: '21 / 9', value: 21 / 9 },
8];
9
10export function Ratios() {
11  return (
12    <div className="grid w-full max-w-md grid-cols-2 gap-4">
13      {ratios.map((ratio) => (
14        <div key={ratio.label} className="flex flex-col gap-1.5">
15          <AspectRatio
16            ratio={ratio.value}
17            className="border-border bg-hatch text-muted-foreground flex items-center justify-center rounded-lg border"
18          >
19            <span className="font-mono text-xs">{ratio.label}</span>
20          </AspectRatio>
21        </div>
22      ))}
23    </div>
24  );
25}

API Reference

AspectRatio

Prop	Type	Default	Description
`ratio`	`number`	`16 / 9`	Width divided by height
`as`	`React.ElementType`	`'div'`	Element to render
`className`	`string`	-	Additional CSS classes, rounding goes here

Found something to improve?

Notice a bug, typo, or missing detail on this page? Help us make the documentation better by opening a GitHub issue.

Create an Issue

PreviousContainer

NextCenter

1import { AspectRatio } from '@/components/ui/aspect-ratio';

3export function Default() {

4 return (

5 <div className="w-full max-w-md">

6 <AspectRatio ratio={16 / 9} className="rounded-xl">

7 <img src="https://picsum.photos/seed/aspect/960/540" alt="Office at golden hour" />

8 </AspectRatio>

9 </div>

10 );

11}

Installation

Copy and paste the following code into your project.

1import React from 'react';
2import { cn } from '../lib/cn';
3
4type AspectRatioOwnProps<E extends React.ElementType> = {
5  as?: E;
6  ratio?: number;
7  className?: string;
8  style?: React.CSSProperties;
9};
10
11type AspectRatioProps<E extends React.ElementType = 'div'> = AspectRatioOwnProps<E> &
12  Omit<React.ComponentPropsWithRef<E>, keyof AspectRatioOwnProps<E>>;
13
14const AspectRatio = <E extends React.ElementType = 'div'>({
15  as,
16  ratio = 16 / 9,
17  className,
18  style,
19  ...props
20}: AspectRatioProps<E>) => {
21  const Component: React.ElementType = as ?? 'div';
22  return (
23    <Component
24      data-slot="aspect-ratio"
25      style={{ aspectRatio: String(ratio), ...style }}
26      className={cn(
27        'relative w-full overflow-hidden [&>iframe]:absolute [&>iframe]:inset-0 [&>iframe]:size-full [&>img]:size-full [&>img]:object-cover [&>video]:size-full [&>video]:object-cover',
28        className,
29      )}
30      {...props}
31    />
32  );
33};
34
35AspectRatio.displayName = 'AspectRatio';
36
37export { AspectRatio };
38export type { AspectRatioProps };

Update the import paths to match your project structure.

Anatomy

1import { AspectRatio } from '@/components/ui/aspect-ratio';

1<AspectRatio ratio={16 / 9} className="rounded-lg">
2  <img src="/cover.jpg" alt="Cover" />
3</AspectRatio>

Examples

Default

1import { AspectRatio } from '@/components/ui/aspect-ratio';
2
3export function Default() {
4  return (
5    <div className="w-full max-w-md">
6      <AspectRatio ratio={16 / 9} className="rounded-xl">
7        <img src="https://picsum.photos/seed/aspect/960/540" alt="Office at golden hour" />
8      </AspectRatio>
9    </div>
10  );
11}

Ratios

Any number works: 1, 4 / 3, 3 / 4, 21 / 9.

1 / 1

4 / 3

3 / 4

21 / 9

1import { AspectRatio } from '@/components/ui/aspect-ratio';
2
3const ratios = [
4  { label: '1 / 1', value: 1 },
5  { label: '4 / 3', value: 4 / 3 },
6  { label: '3 / 4', value: 3 / 4 },
7  { label: '21 / 9', value: 21 / 9 },
8];
9
10export function Ratios() {
11  return (
12    <div className="grid w-full max-w-md grid-cols-2 gap-4">
13      {ratios.map((ratio) => (
14        <div key={ratio.label} className="flex flex-col gap-1.5">
15          <AspectRatio
16            ratio={ratio.value}
17            className="border-border bg-hatch text-muted-foreground flex items-center justify-center rounded-lg border"
18          >
19            <span className="font-mono text-xs">{ratio.label}</span>
20          </AspectRatio>
21        </div>
22      ))}
23    </div>
24  );
25}

Prop

Type

Default

Description

ratio

number

16 / 9

Width divided by height

as

React.ElementType

'div'

Element to render

className

string

Additional CSS classes, rounding goes here