Images

The image utilites are wrapper classes for containing images using the aspect-ratio attribute, the classes can be applied to a individual container like a <figure> element for a single image, or to a grid container for multiple images. Disabled by default, enable with $enable-images: true; in the configuration.scss document.

Single image wrappers (anchor)

The examples below apply the utility classes to the <figure> element, the captions demonstrates the utility names.

Snowy forest with sun filtering through trees — `.auto`

Example HTML

<figure>
<img src="/img/docs/winter-forest-300.webp" alt="Snowy forest with sun filtering through trees" width="300">
<figcaption>Unchanged</figcaption>
</figure>

<figure class="landscape">
<img src="/img/docs/winter-forest-300.webp" alt="Snowy forest with sun filtering through trees" width="300">
<figcaption><code>.landscape</code></figcaption>
</figure>

<figure class="landscape-sm">
<img src="/img/docs/winter-forest-300.webp" alt="Snowy forest with sun filtering through trees" width="300">
<figcaption><code>.landscape-sm</code></figcaption>
</figure>

<figure class="landscape-xs">
<img src="/img/docs/winter-forest-300.webp" alt="Snowy forest with sun filtering through trees" width="300">
<figcaption><code>.landscape-xs</code></figcaption>
</figure>

<figure class="passport">
<img src="/img/docs/winter-forest-300.webp" alt="Snowy forest with sun filtering through trees">
<figcaption><code>.passport</code></figcaption>
</figure>

<figure class="portrait">
<img src="/img/docs/winter-forest-300.webp" alt="Snowy forest with sun filtering through trees">
<figcaption><code>.portrait</code></figcaption>
</figure>

<figure class="portrait-sm">
<img src="/img/docs/winter-forest-300.webp" alt="Snowy forest with sun filtering through trees">
<figcaption><code>.portrait-sm</code></figcaption>
</figure>

Grid gallery (anchor)

If the grid utilities are enabled the utility classes can be applied to a wrapper element to apply the aspect-ratio modifier to all images within the grid making it useful designing gallery orientated content.

Example HTML

<div class="passport g-4 g-2-sm gap-3 mb-3">
<img src="/img/docs/winter-forest-480.webp" alt="Snowy forest with sun filtering through trees">
<img src="/img/docs/winter-forest-480.webp" alt="Snowy forest with sun filtering through trees">
<img src="/img/docs/winter-forest-480.webp" alt="Snowy forest with sun filtering through trees">
<img src="/img/docs/winter-forest-480.webp" alt="Snowy forest with sun filtering through trees">
</div>

Inline styling (anchor)

The aspect-ratio for the utilities are provided by a CSS variable that can be used to customize the ratio inline, it can be used to adjust any of utility classes above to individual images and/or on the grid wrapper to be applied to all images.

Example HTML

<figure class="auto" style="--aspect-ratio: 5 / 1;">
<img src="/img/docs/winter-forest-300.webp" alt="Snowy forest with sun filtering through trees" width="300">
<figcaption><code>--aspect-ratio: 5 / 1;</code></figcaption>
</figure>

<figure class="auto" style="--aspect-ratio: 5 / 2;">
<img src="/img/docs/winter-forest-300.webp" alt="Snowy forest with sun filtering through trees" width="300">
<figcaption><code>--aspect-ratio: 5 / 2;</code></figcaption>
</figure>

<figure class="auto" style="--aspect-ratio: 5 / 3;">
<img src="/img/docs/winter-forest-300.webp" alt="Snowy forest with sun filtering through trees" width="300">
<figcaption><code>--aspect-ratio: 5 / 3;</code></figcaption>
</figure>

Customize (anchor)

The image utilities are compiled from the _image.scss document within the [styles/utilities] directory. The Sass @if rule controls compiling depending on settings in the configuration.scss document.

Styles

@if $enable-images {

.auto, .passport, .landscape, .landscape-sm, .landscape-xs, .portrait, .portrait-sm {
  display: grid;
  grid-template-columns: var(--gtc);
  max-inline-size: var(--width);
}

:where(.auto, .passport, .landscape, .landscape-sm, .landscape-xs, .portrait, .portrait-sm) img {
  object-fit: cover;
  aspect-ratio: var(--aspect-ratio);
  height: 100%;
}

.auto {
  --aspect-ratio: auto;
}

.passport {
  --aspect-ratio: 1 / 1;
}

.landscape {
  --aspect-ratio: 16 / 9;
}

.landscape-sm {
  --aspect-ratio: 3 / 1;
}

.landscape-xs {
  --aspect-ratio: 4 / 1;
}

.portrait {
  --aspect-ratio: 3 / 4;
}

.portrait-sm {
  --aspect-ratio: 4 / 6;
}

} // END [if/images]