Overview

Presents content within the desired proportion.

Preview

Code

import { Aspect-Ratio } from '@inpulse-ui/aspect-ratio';

export function Demo() {
  return (
    <AspectRatio>
      <img src="blocks.jpg" alt="Blocks" />
    </AspectRatio>
  );
}

About

This component is an expansion of the Aspect Ratio developed and maintained by Radix UI.

It is possible to manually control the proportion through the value property but several common proportions are available in a more user-friendly way through the type property.

Using Aspect Ratio is extremely important to avoid Cumulative Layout Shift (CLS) issues. The CLS is one of the main ranking factors for Core Web Vitals and is caused by unexpected changes to the page layout. Using Aspect Ratio helps by reserving the necessary space for certain content as it loads, preventing the page layout from changing abruptly.

Installation

pnpm

pnpm add @inpulse-ui/aspect-ratio

bun

bun add @inpulse-ui/aspect-ratio

yarn

yarn add @inpulse-ui/aspect-ratio

npm

npm install @inpulse-ui/aspect-ratio

API Reference

Root

Contains the content you want to constrain to a given ratio.

Prop	Type	Default Value	Required
asChild	boolean	false	No
ratio	number	1	No
type	enum	squarecirclephotoportraitfeedvideostoriesreelstiktoktvcinema	No

Usage

Wrap your content with the AspectRatio component to apply a specific aspect ratio using the ratio prop to set a custom ratio or type props for predefined ratios. The component accepts an asChild prop to allow for custom HTML elements.

<AspectRatio>
  <img src="blocks.jpg" alt="Blocks" />
</AspectRatio>

Examples

Square

This is the default ratio (1:1). It is not necessary to pass any value to obtain the result below, but we are implementing it just to demonstrate how you could manually change it with any custom value.

Preview

Code

import { Aspect-Ratio } from '@inpulse-ui/aspect-ratio';

export function Demo() {
  return (
    <AspectRatio>
      <img src="blocks.jpg" alt="Blocks" />
    </AspectRatio>
  );
}

Circle

The type with value circle delivers the same proportion as above, however, a round mask is applied to the content.

Preview

Code

import { Aspect-Ratio } from '@inpulse-ui/aspect-ratio';

export function Demo() {
  return (
    <AspectRatio type="circle">
      <img src="blocks.jpg" alt="Blocks" />
    </AspectRatio>
  );
}

Photo

The component assumes the aspect ratio of a photograph. By default, the type with value photo has the same ratio as a photograph in landscape mode (3:2).

Preview

Code

import { Aspect-Ratio } from '@inpulse-ui/aspect-ratio';

export function Demo() {
  return (
    <AspectRatio type="photo">
      <img src="blocks.jpg" alt="Blocks" />
    </AspectRatio>
  );
}

The second option available is the portrait aspect ratio (2:3).

Preview

Code

import { Aspect-Ratio } from '@inpulse-ui/aspect-ratio';

export function Demo() {
  return (
    <AspectRatio type="portrait">
      <img src="blocks.jpg" alt="Blocks" />
    </AspectRatio>
  );
}

Feed

Instagram added a new aspect ratio for images in the feed, which is 4:5.

Preview

Code

import { Aspect-Ratio } from '@inpulse-ui/aspect-ratio';

export function Demo() {
  return (
    <AspectRatio type="feed">
      <img src="blocks.jpg" alt="Blocks" />
    </AspectRatio>
  );
}

Video

The component assumes the aspect ratio of a video. By default, the type with value video has the same ratio as a horizontal video (16:9).

Preview

Code

import { Aspect-Ratio } from '@inpulse-ui/aspect-ratio';

export function Demo() {
  return (
    <AspectRatio type="video">
      <img src="blocks.jpg" alt="Blocks" />
    </AspectRatio>
  );
}

The second option available is the aspect ratio of a standing video (9:16). It can be activated through type with the values: stories, reels or tiktok.

Preview

Code

import { Aspect-Ratio } from '@inpulse-ui/aspect-ratio';

export function Demo() {
  return (
    <AspectRatio type="reels">
      <img src="blocks.jpg" alt="Blocks" />
    </AspectRatio>
  );
}

There are two extra options for videos: tv (4:3) and cinema (21:9).

Audiovisual content

In addition to images, Aspect Ratio can also be used in other types of audiovisual content, such as videos from YouTube, Vimeo, etc. To do this, simply add the content within the Aspect Ratio, as in the example below.

Preview

Code

import { Aspect-Ratio } from '@inpulse-ui/aspect-ratio';

export function Demo() {
  return (
    <AspectRatio type="video">
      <iframe src="https://youtu.be/q3lX2p_Uy9I" />
    </AspectRatio>
  );
}