Image

Last Updated: 2.4.0

NPM Package:

Getting Started

An image. Part of the Bolt “Components” CSS framework that powers the Bolt Design System.

Install via NPM

npm install @bolt/components-image

Image sizes

IMPORTANT: This method of adding classes to images is DEPRECATED.

To specify image size (e.g u-bolt-width-1/1) pass the correct class like so:

{% set classes = create_attribute(imageAttributes | default({})).addClass([
    "c-bolt-image__img",
    "u-bolt-width-1/1",
  ])
%}

Then pass it into the component:

{% include '@bolt-components-image/image.twig' with {
  src: "/images/placeholders/tout-4x3-climber.jpg",
  alt: "A Rock Climber",
  imageAttributes: classes,
} only %}

Usage

  {% include '@bolt-components-image/image.twig' with {
  src: "/src/images/turtle.jpg",
  alt: "A Turtle"
} only %}

Schema

Name	Type	Value(s)	Description	Default
attributes	`object`		A Drupal-style attributes object with extra attributes to append to this component.	N/A
src	`string`		Source url for image.	N/A
alt	`string`		Alt tag for image.	N/A
lazyload	`boolean`	`TRUE` OR `FALSE`	Lazyload can boost performance by loading images on demand, instead of on initial page load.	`true`
no_lazy	`boolean`	`TRUE` OR `FALSE`	Override the default lazyload behavior. Used only on the web component, where the presence of a boolean property always equates to `true`.	`false`
placeholder_color	`string`		A valid CSS background color property shown while image loads.	`hsl(233, 33%, 97%)`
placeholder_image	`string`		Image path or image data shown while image loads.	`data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==`
srcset	`string`		A comma seperated string of image urls and image widths, used for optimizing image loading performance.	N/A
sizes	`string`		A list of one or more strings separated by commas indicating a set of source sizes. Each source size consists of a media condition (omitted for the last item), and a source size value. Learn more.	`auto`
useAspectRatio	`boolean`	`TRUE` OR `FALSE`	DEPRECATED Use the `ratio` prop instead.	`true`
ratio	`string` OR `boolean`		boolean option is DEPRECATED Set the aspect ratio for the image via slash-separated width and height values, e.g. 4/3. Currently required for aspect ratio to be applied properly. Set to "none" to opt out of aspect ratio.	`auto`
width	`number` OR `string`		DEPRECATED Override the default width of the image. If no height is provided, aspect ratio will be maintained.	N/A
height	`number` OR `string`		DEPRECATED Override the default height of the image. If no width is provided, aspect ratio will be maintained.	N/A
cover	`boolean`	`TRUE` OR `FALSE`	Set an image to fill its container.	`false`
imageAttributes	`object`		DEPRECATED A Drupal-style attributes object with extra attributes to append to this component.	N/A

640x480 jpg

500x500 jpg

1151x638 jpg

1151x638 jpeg

2712x2300 png

3000x5336 jpeg

124x33 svg

Src: Root Relative

src: "/images/placeholders/image.jpg",

Src: Source Set

srcset: "/images/placeholders/500x500-200.jpg 200w,/images/placeholders/500x500-320.jpg 320w",

Src only that won't be found in `bolt.data.images`

Src only that won't be found in `bolt.data.images` and not lazy loaded

Src and srcset that won't be found in `bolt.data.images`

Srcset only that won't be found in `bolt.data.images` and not lazy loaded

Srcset only that won't be found in `bolt.data.images` and lazy loaded

Absolute src - not lazy loaded

Absolute src - lazy loaded

Jpg: Lazyload true

Jpg: Lazyload false

Png: Lazyload true

Png: Lazyload false

Svg: Lazyload: true

Svg: Lazyload: false

Custom Height and Width, JPEG (2:1)

Custom Height and Width, PNG (2:1)

Custom Height and Width, SVG (10:1)

Image Zoom

When used with the device viewer component, the image component can used to create a "zoomed" state (`magnify` must be set to `true` on the device viewer).

Web Component Usage

Bolt Image is a web component that renders a semantic <img> tag with Bolt styles. All that's required to make a <bolt-image> are the src and alt attributes.

<bolt-image src="/images/placeholders/tout-4x3-climber.jpg" alt="A Rock Climber"></bolt-image>

Responsize Images

Optionally, pass srcset and sizes to <bolt-image> for responsive images.

<bolt-image src="/images/placeholders/tout-4x3-climber.jpg" srcset="/images/placeholders/tout-4x3-climber-320.jpg 320w" sizes="auto" alt="A Rock Climber"></bolt-image>

Setting the Aspect-ratio

Setting the aspect ratio on an image provides a placeholder while the image is loading. Do this by adding the ratio attribute with the image's aspect-ratio as slash-separated values, e.g. "4/3" or "400/300".

<bolt-image src="/images/placeholders/tout-4x3-climber.jpg" alt="A Rock Climber" ratio="4/3"></bolt-image>

Lazyloading

Lazyloading is on by default. Turn it off with the no-lazy attribute.

<bolt-image src="/images/placeholders/tout-4x3-climber.jpg" alt="A Rock Climber" no-lazy></bolt-image>

Custom Placeholder

Placeholder image and color options can be set via the attributes placeholder-image and placeholder-color where "image" is an image path and "color" is a valid CSS background-color. Note: the ratio attribute must be provided for placholder image or color to display.

<bolt-image src="/images/placeholders/tout-4x3-climber.jpg" alt="A Rock Climber" ratio="4/3" placeholder-color="#D3D3D3" placeholder-image="http://placehold.it/400x300"></bolt-image>