Aspect-ratio

Aspect-ratio utilities for single or grouped elements with module mixins for responsive modifiers.

Utilities (anchor)

See the examples below to view how single and child element ratios work.

Aspect-ratio utility names and property values
Utility name Property values
Single ratios
.ratio aspect-ratio: var(--ratio)
.ratio-auto aspect-ratio: auto
.ratio-1x1 aspect-ratio: 1 / 1
.ratio-16x9 aspect-ratio: 16 / 9
.ratio-5x2 aspect-ratio: 5 / 2
.ratio-4x1 aspect-ratio: 4 / 1
.ratio-3x4 aspect-ratio: 3 / 4
.ratio-4x6 aspect-ratio: 4 / 6
Child ratios
.child-ratio aspect-ratio: var(--ratio)
.child-ratio-auto aspect-ratio: auto
.child-ratio-1x1 aspect-ratio: 1 / 1
.child-ratio-16x9 aspect-ratio: 16 / 9
.child-ratio-5x2 aspect-ratio: 5 / 2
.child-ratio-4x1 aspect-ratio: 4 / 1
.child-ratio-3x4 aspect-ratio: 3 / 4
.child-ratio-4x6 aspect-ratio: 4 / 6

Responsive mixins (anchor)

Responsive modifier mixins are provided to include where required in custom breakpoints, the utilities available use the following modifier class naming convention:

.ratio-16x9
.ratio-16x9-xxl
.ratio-16x9-xl
.ratio-16x9-lg
.ratio-16x9-md
.ratio-16x9-sm
.ratio-16x9-xs
.ratio-16x9-xxs

Examples (anchor)

Aspect-ratio properties work best with images or other media content but can be used with any content with preset block or inline size values. All the image examples below use the object-fit: cover property utility provided by the optional object-fit styles to clip the image to retain their original aspect-ratio.

Single elements (anchor)

Head on shot of elephant with big tusks and ears flared staring down camera .ratio-4x6
Head on shot of elephant with big tusks and ears flared staring down camera .ratio-3x4
Head on shot of elephant with big tusks and ears flared staring down camera .ratio-auto
Head on shot of elephant with big tusks and ears flared staring down camera .ratio-1x1
Head on shot of elephant with big tusks and ears flared staring down camera .ratio-16x9
Head on shot of elephant with big tusks and ears flared staring down camera .ratio-5x2
Head on shot of elephant with big tusks and ears flared staring down camera .ratio-4x1
Example HTML

The <div> is not required, it's only used to contain the code examples with the images.

<div>
<img src="/img/elephant-480.webp" class="object-cover ratio-4x6" alt="Head on shot of elephant with big tusks and ears flared staring down camera" width="200">
<code>.ratio-4x6</code>
</div>

<div>
<img src="/img/elephant-480.webp" class="object-cover ratio-3x4" alt="Head on shot of elephant with big tusks and ears flared staring down camera" width="200">
<code>.ratio-3x4</code>
</div>

<div>
<img src="/img/elephant-480.webp" class="object-cover ratio-auto" alt="Head on shot of elephant with big tusks and ears flared staring down camera" width="200">
<code>.ratio-auto</code>
</div>

<div>
<img src="/img/elephant-480.webp" class="object-cover ratio-1x1" alt="Head on shot of elephant with big tusks and ears flared staring down camera" width="200">
<code>.ratio-1x1</code>
</div>

<div>
<img src="/img/elephant-480.webp" class="object-cover ratio-16x9" alt="Head on shot of elephant with big tusks and ears flared staring down camera" width="200">
<code>.ratio-16x9</code>
</div>

<div>
<img src="/img/elephant-480.webp" class="object-cover ratio-5x2" alt="Head on shot of elephant with big tusks and ears flared staring down camera" width="200">
<code>.ratio-5x2</code>
</div>

<div>
<img src="/img/elephant-480.webp" class="object-cover ratio-4x1" alt="Head on shot of elephant with big tusks and ears flared staring down camera" width="200">
<code>.ratio-4x1</code>
</div>

Child ratios (anchor)

The .child-ratio-* utilities are applied to a container class so all child elements use the aspect-ratio being provided, the optional object-fit styles also include .child-object-* utilities to use with the ratios if required.

Useful for a gallery, the following uses the grid and gaps utilities to contain the images within a responsive grid.

A rocky stream next to a small copse of pinetrees on a grassy bank A red fox with one eye blue and the other brown looking directly at camera View of distant mountains and valleys scenery bathed in hazy sunlight A small white and brown bird with orange chest colors sitting on a tree branch
Example HTML 
<div class="child-object-cover child-ratio-1x1 grid g-2-xs g-4 gap-3 mb-3">
<img src="/img/rocky-stream-480.webp" alt="A rocky stream next to a small copse of pinetrees on a grassy bank">
<img src="/img/red-fox-480.webp" alt="A red fox with one eye blue and the other brown looking directly at camera">
<img src="/img/hazy-mountains-480.webp" alt="View of distant mountains and valleys scenery bathed in hazy sunlight">
<img src="/img/bird-on-branch-480.webp" alt="A small white and brown bird with orange chest colors sitting on a tree branch">
</div>

Applied to a <figure> element that also includes a <figcaption> with the image (above or below).

Snowy forest clearing with sunlight filtering through tall trees
Winter forest 16x9
Snowy forest clearing with sunlight filtering through tall trees
Winter forest 5x2
Snowy forest clearing with sunlight filtering through tall trees
Winter forest 4x1
Example HTML 
<figure class="child-ratio-16x9 child-object-cover">
<img src="/img/winter-forest-300.webp" alt="Snowy forest clearing with sunlight filtering through tall trees" width="300">
<figcaption>Winter forest 16x9</figcaption>
</figure>

<figure class="child-ratio-5x2 child-object-cover">
<img src="/img/winter-forest-300.webp" alt="Snowy forest clearing with sunlight filtering through tall trees" width="300">
<figcaption>Winter forest 5x2</figcaption>
</figure>

<figure class="child-ratio-4x1 child-object-cover">
<img src="/img/winter-forest-300.webp" alt="Snowy forest clearing with sunlight filtering through tall trees" width="300">
<figcaption>Winter forest 4x1</figcaption>
</figure>

Inline ratios (anchor)

Custom aspect-ratios can also be included using inline styles with a variable utility class for creating custom aspect-ratios.

For single elements the .ratio class is used:

Desert sand dunes with blue sky background Desert sand dunes with blue sky background Desert sand dunes with blue sky background
Example HTML 
<img src="/img/desert-480.webp" alt="Desert sand dunes with blue sky background" width="300" class="object-cover ratio" style="--ratio: 15 / 7;">
<img src="/img/desert-480.webp" alt="Desert sand dunes with blue sky background" width="300" class="object-cover ratio" style="--ratio: 15 / 6;">
<img src="/img/desert-480.webp" alt="Desert sand dunes with blue sky background" width="300" class="object-cover ratio" style="--ratio: 15 / 5;">

For child elements the .child-ratio class is used:

Head on shot of elephant with big tusks and ears flared staring down camera Close up of green frog sitting on leaf of tree. Male lion with healthy main staring into distance. A red fox with one eye blue and the other brown looking directly at camera
Example HTML 
<div class="child-ratio child-object-cover grid g-2-xs g-4 gap-3 mb-3" style="--ratio: 15 / 7">
<img src="/img/elephant-480.webp" alt="Head on shot of elephant with big tusks and ears flared staring down camera">
<img src="/img/frog-540.webp" alt="Close up of green frog sitting on leaf of tree.">
<img src="/img/lion-540.webp" alt="Male lion with healthy main staring into distance.">
<img src="/img/red-fox-480.webp" alt="A red fox with one eye blue and the other brown looking directly at camera">
</div>

Using the module (anchor)

To use the module load the StyleMods scss directory as follows (changing the path to suit the source files location as required) then include the Sass mixin anywhere below.

@use "stylemods/scss" as *;
@include aspect-ratio-css;

// Example breakpoint
@media (width <= 480px) {
  @include aspect-ratio-sm-css;
}

Source code (anchor)

aspect-ratio.scss 
// ---------------------------------------------------------- 
// Aspect ratio
// ----------------------------------------------------------
$aspect-ratio-values: (
  "auto": auto,
  "1x1": #{"1 / 1"},
  "16x9": #{"16 / 9"},
  "5x2": #{"5 / 2"},
  "4x1": #{"4 / 1"},
  "3x4": #{"3 / 4"},
  "4x6": #{"4 / 6"},
) !default;

@mixin aspect-ratio-css {
  .ratio {
    aspect-ratio: var(--ratio);
  }
  
  @each $name, $value in $aspect-ratio-values {
    .ratio-#{$name} {
      aspect-ratio: $value;     
    }   
  }
  
  .child-ratio *:not(figcaption) {
    aspect-ratio: var(--ratio);
  }
  
  @each $name, $value in $aspect-ratio-values {
    .child-ratio-#{$name} *:not(figcaption) {
      aspect-ratio: $value;   
    }  
  }
}


// Breakpoints
@mixin aspect-ratio-xxl-css {
  @each $name, $value in $aspect-ratio-values {
    .ratio-#{$name}-xxl {
      aspect-ratio: #{$value};        
    }    
  }
  
  @each $name, $value in $aspect-ratio-values {
    .child-ratio-#{$name}-xxl *:not(figcaption) {
      aspect-ratio: $value;   
    }  
  }
}

@mixin aspect-ratio-xl-css {
  @each $name, $value in $aspect-ratio-values {
    .ratio-#{$name}-xl {
      aspect-ratio: #{$value};        
    }    
  }

  @each $name, $value in $aspect-ratio-values {
    .child-ratio-#{$name}-xl *:not(figcaption) {
      aspect-ratio: $value;   
    }  
  }
}

@mixin aspect-ratio-lg-css {
  @each $name, $value in $aspect-ratio-values {
    .ratio-#{$name}-lg {
      aspect-ratio: #{$value};        
    }    
  }

  @each $name, $value in $aspect-ratio-values {
    .child-ratio-#{$name}-lg *:not(figcaption) {
      aspect-ratio: $value;   
    }  
  }
}

@mixin aspect-ratio-md-css {
  @each $name, $value in $aspect-ratio-values {
    .ratio-#{$name}-md {
      aspect-ratio: #{$value};        
    }    
  }

  @each $name, $value in $aspect-ratio-values {
    .child-ratio-#{$name}-md *:not(figcaption) {
      aspect-ratio: $value;   
    }  
  }
}

@mixin aspect-ratio-sm-css {
  @each $name, $value in $aspect-ratio-values {
    .ratio-#{$name}-sm {
      aspect-ratio: #{$value};        
    }    
  }

  @each $name, $value in $aspect-ratio-values {
    .child-ratio-#{$name}-sm *:not(figcaption) {
      aspect-ratio: $value;   
    }  
  }
}

@mixin aspect-ratio-xs-css {
  @each $name, $value in $aspect-ratio-values {
    .ratio-#{$name}-xs {
      aspect-ratio: #{$value};        
    }    
  }

  @each $name, $value in $aspect-ratio-values {
    .child-ratio-#{$name}-xs *:not(figcaption) {
      aspect-ratio: $value;   
    }  
  }
}

@mixin aspect-ratio-xxs-css {
  @each $name, $value in $aspect-ratio-values {
    .ratio-#{$name}-xxs {
      aspect-ratio: #{$value};        
    }    
  }

  @each $name, $value in $aspect-ratio-values {
    .child-ratio-#{$name}-xxs *:not(figcaption) {
      aspect-ratio: $value;   
    }  
  }
}