Ratios

Aspect ratio utilities for maintaining proportional dimensions on embedded content and block elements across breakpoints.

@layer utilities

Overview

Use the ratio utility to manage the aspect ratios of content like <iframe>s, <embed>s, <video>s, and <object>s. These helpers also can be used on any standard HTML child element (e.g., a <div> or <img>). Customize the available aspect ratios with the Sass variable or the utility API.

Pro-Tip! You don’t need frameborder="0" on your <iframe>s as we override that for you in Reboot.

Example

Add your ratio utility to the element you want to modify, like an <iframe>, <video>, or less semantic elements like <div>. Ratio utilities also pair well with any width utilities, as shown below. Customize the available aspect ratios with the Sass variable or the utility API.

Heads up—you can omit frameborder="0" on your <iframe>s as that is overridden for you in Reboot.

<iframe class="w-100 ratio-16x9" src="https://www.youtube.com/embed/LO2RPDZkY88?rel=0" title="YouTube video" allowfullscreen></iframe>

Swap the .ratio-* class for a different aspect ratio.

Auto

1×1

4×3

16×9

21×9

<div class="ratio-auto">
  <div>Auto</div>
</div>
<div class="w-25 ratio-1x1">
  <div>1×1</div>
</div>
<div class="w-50 ratio-4x3">
  <div>4×3</div>
</div>
<div class="w-75 ratio-16x9">
  <div>16×9</div>
</div>
<div class="w-100 ratio-21x9">
  <div>21×9</div>
</div>

Custom ratios

Each .ratio-* class includes a CSS custom property (or CSS variable) in the selector. You can override this CSS variable to create custom aspect ratios on the fly with some quick math on your part.

For example, to create a 2x1 aspect ratio, set --cx-aspect-ratio: 50% on the .ratio-auto.

2x1

<div class="w-25 ratio-auto" style="--cx-aspect-ratio: 2;">
  <div>2x1</div>
</div>

This CSS variable makes it easy to modify the aspect ratio across breakpoints. The following is 4x3 to start, but changes to a custom 2x1 at the medium breakpoint.

4x3, then 2x1

<div class="w-25 ratio-4x3">
  <div>4x3, then 2x1</div>
</div>

CSS

Ratio utilities are generated from Sass maps via the utilities API.

Reference

The table lists all ratio utilities and their CSS properties.

Class	Properties
`.ratio-auto`	`--cx-aspect-ratio: auto;`
`.ratio-1x1`	`--cx-aspect-ratio: 1 / 1;`
`.ratio-4x3`	`--cx-aspect-ratio: 4 / 3;`
`.ratio-16x9`	`--cx-aspect-ratio: 16 / 9;`
`.ratio-21x9`	`--cx-aspect-ratio: 21 / 9;`

Sass maps

Ratio utilities are generated from the Sass map in scss/config/_defaults.scss.

$aspect-ratios: (
  "auto": auto,
  "1x1": #{"1 / 1"},
  "4x3": #{"4 / 3"},
  "16x9": #{"16 / 9"},
  "21x9": #{"21 / 9"}
);

Utilities API

Ratio utilities are declared in scss/utilities/_index.scss using the utilities API.

"aspect-ratio-attr": (
  selector: "attr-includes",
  class: "ratio-",
  property: aspect-ratio,
  values: var(--aspect-ratio),
),
"aspect-ratio": (
  // property: aspect-ratio,
  property: --aspect-ratio,
  class: ratio,
  values: $aspect-ratios
),