Image Component in Bolt

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([

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 %}
  {% include '@bolt-components-image/image.twig' with {
  src: "/src/images/turtle.jpg",
  alt: "A Turtle"
} only %}

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)

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


Source url for image.


Alt tag for image.


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

boolean true
  • 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.

boolean false
  • true or false

A valid CSS background color property shown while image loads.

string hsl(233, 33%, 97%)

Image path or image data shown while image loads.


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


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

Use the ratio prop instead.

boolean true
  • true or false

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 or boolean auto

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


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

number or string

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

number or string

Set an image to fill its container.

boolean false
  • true or false

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


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
A Rock Climber A Rock Climber

640x480 jpg

A Rock Climber A Rock Climber

500x500 jpg

Bill Murray Bill Murray

1151x638 jpg

Mountains Mountains

1151x638 jpeg


2712x2300 png

decision hub chart

3000x5336 jpeg

device screenshot device screenshot

124x33 svg

logo paypal svg

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

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