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)

Load StyleMods as demonstrated (change file path 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;
}

See the using modules page for more information including how to compile the modules in cascade layers and include and reuse them in multiple source files.

Using the framework (anchor)

Using the recommended custom setup enable the styles (and required breakpoints) in an overrides document:

overrides.scss 
@use "stylemods/scss/configuration" as *;
$enable-aspect-ratio:     true;
$enable-aspect-ratio-sm:  true;

Include the overrides and the framework styles with your custom document for compiling the framework:

custom.scss 
@use "overrides";
@use "stylemods/scss/stylemods";

See using the framework for more information including how the styles can also be compiled within cascade layers.

Source code (anchor)

The modules and framework use the same source code, see Sass maps to learn how to customize the values below.

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;   
    }  
  }
}