image docs

Image

A responsive image embed.

Published Last updated: 5.0.0 Change log Github NPM
Twig Usage 
{% include '@bolt-elements-image/image.twig' with {
  fill: true,
  attributes: {
    alt: 'Image alt text',
    src: 'path/image.jpg',
    width: 500,
    height: 500,
  },
} only %}
 Schema
Note: when assigning component props as HTML attributes on a web component, make sure to use kebab-case.
Prop Name Description Type Default Value Option(s)
attributes

A Drupal-style attributes object with extra attributes to append to this element.

 object —
  • —
fill

Render the image 100% wide, filling up the full width of its parent container.

 boolean —
  • —
background

Render the image as a background image. This sets the image to be absolute positioned, only use this prop if the image is inside a non-static container.

 boolean —
  • —
Install Install 
npm install @bolt/elements-image
Dependencies @bolt/core-v3.x

image

Basic Image An image element embeds a responsive graphic on the page. Important Notes: To make an image accessible to screen readers and other assistive technology, make sure to include text description via the alt attribute. To indicate an image as decoration, leave the alt attribute blank, do not remove it. For example: alt="". It is best practice to always define the width and height attributes, so the space that the image would take up is already calculated before the image finishes loading. This helps to reduce cumulative layout shifts. If responsiveness is not needed, please use a plain <img> element instead. Demo Alt text.
Twig
{% include '@bolt-elements-image/image.twig' with {
  attributes: {
    alt: 'Alt text.',
    src: 'path/image.jpg',
    width: 400,
    height: 225,
  },
} only %}
HTML
<img alt="Alt text." src="path/image.jpg" width=400 height=225 class="e-bolt-image">

image srcset and sizes

Responsive Resolutions Use the srcset and sizes attributes to render various resolutions of the same image at specific breakpoints. Important Notes: The srcset attribute accepts one or more strings separated by commas, indicating possible image sources for the user agent to use. Each string is composed of a URL to an image and a width descriptor. For example, srcset="image/400x300.jpg 400w, image/800x600.jpg 800w, image/1600x1200.jpg 1600w". The sizes attribute should contain a number value with the vw unit. The number should be determined by the largest size which the image could take up relative to screen size. For example, a large image taking up full width of a page should use something around 96vw to 100vw; a small image taking up 1 column of a 3-column layout should use 33vw. For more advanced use cases, reference the MDN article on responsive images. Demo Alt text.
Twig
{% include '@bolt-elements-image/image.twig' with {
  attributes: {
    alt: 'Alt text.',
    src: 'path/image-800.jpg',
    srcset: 'path/image-400.jpg 400w, path/image-800.jpg 800w',
    sizes: '50vw',
    width: 800,
    height: 450,
  },
} only %}
HTML
<img alt="Alt text." src="path/image-800.jpg" srcset="path/image-400.jpg 400w, path/image-800.jpg 800w" sizes="50vw" width=800 height=450 class="e-bolt-image">

image fill

Fill Image The fill prop will stretch the image to fill up 100% width of its parent container, ignoring the image’s true width and height. Important Notes: Even though they are ignored, it is best practice to always define the width and height attributes, so the space that the image would take up is already calculated before the image finishes loading. This helps to reduce cumulative layout shifts. Demo Alt text.
Twig
{% include '@bolt-elements-image/image.twig' with {
  fill: true,
  attributes: {
    alt: 'Alt text.',
    src: 'path/image-800.jpg',
    srcset: 'path/image-400.jpg 400w, path/image-800.jpg 800w',
    sizes: '96vw',
    width: 800,
    height: 450,
  },
} only %}
HTML
<img alt="Alt text." src="path/image-800.jpg" srcset="path/image-400.jpg 400w, path/image-800.jpg 800w" sizes="96vw" width=800 height=450 class="e-bolt-image e-bolt-image--fill">

image background

Simple Background Image The background prop will transform the image into a background image. Important Notes: The image must be placed into a container that is not positioned static (e.g. absolute, fixed, relative, or sticky). It must be the first child of said container. All foreground content of said container must be positioned relative. Most background images are decorative, it is reasonable to leave the alt attribute blank for such case. It is recommended to use the srcset and sizes attributes for better performance. Demo
This is a non-static container
Twig
<div style="position:relative;">
  // This image will fill up the non-static parent container
  {% include '@bolt-elements-image/image.twig' with {
    background: true,
    attributes: {
      src: 'path/image-1600.jpg',
      srcset: 'path/image-400.jpg 400w, path/image-800.jpg 800w, path/image-1600.jpg 1600w',
      sizes: '100vw',
      width: 1600,
      height: 900,
    },
  } only %}

  <div style="position:relative;">
    // Content goes here after the image
  </div>
</div>
HTML
<div style="position:relative;">
  // This image will fill up the non-static parent container
  <img src="path/image-1600.jpg" srcset="path/image-400.jpg 400w, path/image-800.jpg 800w, path/image-1600.jpg 1600w" sizes="100vw" width=1600 height=900 class="e-bolt-image e-bolt-image--bg" alt="">

  <div style="position:relative;">
    // Content goes here after the image
  </div>
</div>

image use case background fit and position

Use Case: Advanced Background Image In addition to the background prop, there are 2 CSS custom properties available for use to further customize background image(s). They are commonly used when multiple decorative background images are required. Important Notes: --e-bolt-image-fit Setting this to none will allow the background image to stay exactly at its specified width and height. Setting this to contain will allow the background image to be contained within its parent container. No cropping will happen to the image. By default, this is set to cover. More advanced options are supported, reference the CSS property object-fit. --e-bolt-image-position This custom property accepts pair values: x-axis and y-axis position tokens (e.g. top left, top center, top right, bottom left, bottom center, bottom right, left center, right center, center center). By default, this is set to center center. More advanced options are supported, reference the CSS property object-position. Demo Setting fit to contain
Setting fit to none and position to exact directions
Twig
<div style="position:relative;">
  // This background image will not be cropped and it is positioned to center of the non-static parent container.
  {% include '@bolt-elements-image/image.twig' with {
    background: true,
    attributes: {
      src: 'path/image.jpg',
      width: 500,
      height: 500,
      style: '--e-bolt-image-fit: contain; --e-bolt-image-position: center center;',
    },
  } only %}

  // This background image will not stretch and it is positioned to top left of the non-static parent container.
  {% include '@bolt-elements-image/image.twig' with {
    background: true,
    attributes: {
      src: 'path/image.jpg',
      width: 150,
      height: 150,
      style: '--e-bolt-image-fit: none; --e-bolt-image-position: top left;',
    },
  } only %}
</div>
HTML
<div style="position:relative;">
  // This background image will not be cropped and it is positioned to center of the non-static parent container.
  <img src="path/image.jpg" width=500 height=500 style="--e-bolt-image-fit: contain; --e-bolt-image-position: center center;" class="e-bolt-image e-bolt-image--bg" alt="">

  // This background image will not stretch and it is positioned to top left of the non-static parent container.
  <img src="path/image.jpg" width=150 height=150 style="--e-bolt-image-fit: none; --e-bolt-image-position: top left;" class="e-bolt-image e-bolt-image--bg" alt="">
</div>

image use case art direction

Use Case: Art Direction The <picture> HTML element can help with art directing a particular graphical area of a page. Important Notes: When to use just the image element: loading different resolutions of the same image based on screen size. When to use the <picture> HTML element: loading completely different images altogether based on screen size. The srcset attribute should be used. The x descriptor should be used after the image file URL. This helps with loading higher resolution images for monitors with higher DPI. The media attribute should be used to indicate multiple breakpoints. For more advanced use cases, reference the MDN article on responsive images. Demo
Alt text.

Completely different images are loaded via the <picture> HTML element, resize this page to see the image on the left change.
Twig
<picture>
  // Set the image sources
  <source srcset="path/image-2x.jpg 2x, path/image.jpg" media="(min-width: 1000px)">
  <source srcset="path/image-b-1200.jpg 2x, path/image-b-600.jpg" media="(min-width: 600px)">
  <source srcset="path/image-a-600.jpg 2x, path/image-a-300.jpg" media="(min-width: 300px)">

  // Set the fallback image
  {% include '@bolt-elements-image/image.twig' with {
    attributes: {
      alt: 'Alt text.',
      src: 'path/image.jpg',
      srcset: 'path/image-2x.jpg 2x',
      width: 1000,
      height: 500,
    },
  } only %}
</picture>
HTML
<picture>
  // Set the image sources
  <source srcset="path/image-2x.jpg 2x, path/image.jpg" media="(min-width: 1000px)">
  <source srcset="path/image-b-1200.jpg 2x, path/image-b-600.jpg" media="(min-width: 600px)">
  <source srcset="path/image-a-600.jpg 2x, path/image-a-300.jpg" media="(min-width: 300px)">

  // Set the fallback image
  <img src="path/image.jpg" srcset="path/image-2x.jpg 2x" width=1000 height=500 class="e-bolt-image" alt="Alt text.">
</picture>