image docs

Image

A container for displaying responsive image.

Published Last updated: 2.26.2 Change log Github NPM
Twig Usage
  {% include '@bolt-components-image/image.twig' with {
  src: "/src/images/turtle.jpg",
  alt: "A Turtle"
} 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 component.

object
src

Source url for image.

string
alt

Alt tag for image.

string
lazyload

Lazyload can boost performance by loading images on demand, instead of on initial page load.

boolean true
  • true or false
no_lazy

Override the default lazyload behavior. Used only on the web component, where the presence of a boolean property always equates to true.

boolean false
  • true or false
placeholder_color

A valid CSS background color property shown while image loads.

string hsl(233, 33%, 97%)
placeholder_image

Image path or image data shown while image loads.

string data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==
srcset

A comma seperated string of image urls and image widths, used for optimizing image loading performance.

string
sizes

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.

string auto
useAspectRatio
(deprecated)

Use the ratio prop instead.

boolean true
  • true or false
ratio

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.

string , boolean auto
max_width

Set the max-width of the image as a valid CSS value, e.g. '300px' or '50%'.

string
width
(deprecated)

Override the default width of the image. If no height is provided, aspect ratio will be maintained.

height
(deprecated)

Override the default height of the image. If no width is provided, aspect ratio will be maintained.

cover

Set an image to fill its container.

boolean false
  • true or false
imageAttributes
(deprecated)

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

object
valign

Allows the image's vertical alignment behavior to be customized in certain situations (ex. background images). This can be configured via a pre-defined position (top | center | bottom) or via specific pixel or percent offset (ex. 30%).

string center
align

Allows the image's horizontal alignment behavior to be customized in certain situations (ex. background images). This can be configured via a pre-defined position (left | center | right) or via specific pixel or percent offset (ex. 30%).

string center
Install Install
  npm install @bolt/components-image
Dependencies @bolt/components-ratio @bolt/core-v3.x @bolt/element @bolt/lazy-queue lazysizes

image

A Rock Climber A Rock Climber

image size variations

640x480 jpg

A Rock Climber A Rock Climber

500x500 jpg

Bill Murray Bill Murray

1151x638 jpg

Mountains Mountains

1151x638 jpeg

Mountains

2712x2300 png

decision hub chart

3000x5336 jpeg

device screenshot device screenshot

124x33 svg

logo paypal svg

image source variations

Src: Root Relative

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

Src: Source Set

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

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

Bill Murray Bill Murray

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

Bill Murray Bill Murray

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

Bill Murray Bill Murray

Absolute src - not lazy loaded

Wikipedia Example

Absolute src - lazy loaded

Wikipedia Example

image lazyload variations

Jpg: Lazyload true

Bill Murray Bill Murray

Jpg: Lazyload false

Bill Murray Bill Murray

Png: Lazyload true

decision hub chart

Png: Lazyload false

decision hub chart

Svg: Lazyload: true

logo paypal svg

Svg: Lazyload: false

logo paypal svg

Custom Height and Width, JPEG (2:1)

Bill Murray Bill Murray

Custom Height and Width, PNG (2:1)

decision hub chart

Custom Height and Width, SVG (10:1)

logo paypal svg

Custom Max-Width, JPG (200px)

rocks in Yosemite rocks in Yosemite

image with web components

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>