@tailwindcss/aspect-ratio

What is @tailwindcss/aspect-ratio?

@tailwindcss/aspect-ratio is a Tailwind CSS plugin that provides utilities for controlling the aspect ratio of an element. This is particularly useful for embedding responsive videos, images, or any other content that needs to maintain a specific aspect ratio.

What are @tailwindcss/aspect-ratio's main functionalities?

Aspect Ratio Utilities

This feature allows you to set a specific aspect ratio for an element. In this example, the aspect ratio is set to 16:9, which is commonly used for videos.

<div class="aspect-w-16 aspect-h-9">
  <iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ" title="YouTube video" allowfullscreen></iframe>
</div>

Custom Aspect Ratios

You can also set custom aspect ratios using the aspect-w-{n} and aspect-h-{n} classes. In this example, the aspect ratio is set to 4:3, which is often used for photographs.

<div class="aspect-w-4 aspect-h-3">
  <img src="path/to/image.jpg" alt="Example Image">
</div>

Square Aspect Ratio

For elements that need to maintain a square aspect ratio, you can use the aspect-w-1 and aspect-h-1 classes. This ensures the element remains a perfect square.

<div class="aspect-w-1 aspect-h-1">
  <img src="path/to/square-image.jpg" alt="Square Image">
</div>

Other packages similar to @tailwindcss/aspect-ratio

react-aspect-ratio

react-aspect-ratio is a React component for aspect ratio control. It provides a simple way to maintain aspect ratios for embedded content in React applications. Unlike @tailwindcss/aspect-ratio, which is a utility-first CSS framework plugin, react-aspect-ratio is specifically designed for React.

css-aspect-ratio

css-aspect-ratio is a lightweight CSS library for maintaining aspect ratios. It offers a similar functionality to @tailwindcss/aspect-ratio but is not tied to any specific CSS framework, making it more flexible for use in various projects.

README

@tailwindcss/aspect-ratio

A plugin that provides a composable API for giving elements a fixed aspect ratio.

Installation

Install the plugin from npm:

# Using npm
npm install @tailwindcss/aspect-ratio

# Using Yarn
yarn add @tailwindcss/aspect-ratio

Then add the plugin to your tailwind.config.js file:

// tailwind.config.js
module.exports = {
  theme: {
    // ...
  },
  plugins: [
    require('@tailwindcss/aspect-ratio'),
    // ...
  ],
}

Usage

Combine the aspect-w-{n} and aspect-h-{n} classes to specify the aspect ratio for an element:

<div class="aspect-w-16 aspect-h-9">
  <iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</div>

Use aspect-none to remove any aspect ratio behavior:

<div class="aspect-w-16 aspect-h-9 lg:aspect-none">
  <!-- ... -->
</div>

When removing aspect ratio behavior, if nested elements have w-{n} or h-{n} classes, ensure they are re-declared with a matching breakpoint prefix:

<div class="aspect-w-16 aspect-h-9 lg:aspect-none">
  <img src="..." alt="..." class="w-full h-full object-center object-cover lg:w-full lg:h-full" />
</div>

Note that due to the way this currently needs to be implemented (the old padding-bottom trick) you need to assign the aspect ratio to a parent element, and make the actual element you are trying to size the only child of that parent.

Once the aspect-ratio property is supported in modern browsers, we'll add official support to Tailwind CSS itself and deprecate this plugin.

Aspect ratio classes up to 16 are generated by default:

Width	Height
aspect-w-1	aspect-h-1
aspect-w-2	aspect-h-2
aspect-w-3	aspect-h-3
aspect-w-4	aspect-h-4
aspect-w-5	aspect-h-5
aspect-w-6	aspect-h-6
aspect-w-7	aspect-h-7
aspect-w-8	aspect-h-8
aspect-w-9	aspect-h-9
aspect-w-10	aspect-h-10
aspect-w-11	aspect-h-11
aspect-w-12	aspect-h-12
aspect-w-13	aspect-h-13
aspect-w-14	aspect-h-14
aspect-w-15	aspect-h-15
aspect-w-16	aspect-h-16

Configuration

You can configure which values and variants are generated by this plugin under the aspectRatio key in your tailwind.config.js file:

// tailwind.config.js
module.exports = {
  theme: {
    aspectRatio: {
      1: '1',
      2: '2',
      3: '3',
      4: '4',
    }
  },
  variants: {
    aspectRatio: ['responsive', 'hover']
  }
}