article

article docs

Article

An editorial container that styles children HTML elements.

Published Last updated: 5.0.0 Change log Github NPM
Twig Usage
{% include '@bolt-elements-article/article.twig' with {
  content: 'This is an article.',
} 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
content *

Content of the article.

any
tag

Set the HTML tag for the content container.

string article
  • article or div
Install Install
npm install @bolt/elements-article
Dependencies @bolt/core-v3.x

article

Basic Article An Article element can be used for any free-form content areas where a WYSIWYG editor is enabled. Basic HTML elements are styled within the Article element. Important Notes: Even though plain <table> elements are styled, they are not responsive. Please wrap all <table> elements with <bolt-table> web component to enable responsive styles (JavaScript required). View Table ComponentAs for <pre> and <code> elements, they do not have syntax highlighting. To enable syntax highlighting, please use <code> web component instead (JavaScript required). View Code Snippet Component Demo

The is a list of all supported plain HTML elements:

  • p
  • dl
  • ol
  • ul
  • header
  • section
  • h1 ~ h6
  • blockquote
  • details
  • figure
  • small
  • table
  • code
  • kbd
  • pre
  • hr

The following is a kitchen sink of all supported plain HTML elements:

H1 heading text

H2 heading text

H3 heading text

H4 heading text

H5 heading text
H6 heading text

Text: bold, italic, linked, code, kbd, small, superscript, subscript.

  • First level unordered item
  • First level unordered item
    1. Second level ordered item
      • Third level unordered item
      • Third level unordered item
    2. Second level ordered item
  • First level unordered item
  1. First level ordered item
  2. First level ordered item
    • Second level unordered item
      1. Third level ordered item
      2. Third level ordered item
    • Second level unordered item
  3. First level ordered item
Summary sums up the details

Details elaborate on the summary.

Definition list
A list of text and description.
Morgawr
A sea serpent.
Owlman
A giant owl-like creature.
pre {
  padding: .5em 1em; color: black; border-left: 5px solid; background-color: white;
}

Pull Quote. Darkness cannot drive out darkness; only light can do that. Hate cannot drive out hate; only love can do that.

The time is always right to do what is right.

Figure caption
Col1 Col2 Col3
Row1 Row1 Row1
Row2 Row2 Row2
Twig
// Render content
{% set article_content %}
  <h1>
    H1 heading text
  </h1>
  <h2>
    H2 heading text
  </h2>
  <h3>
    H3 heading text
  </h3>
  <h4>
    H4 heading text
  </h4>
  <h5>
    H5 heading text
  </h5>
  <h6>
    H6 heading text
  </h6>
  <p>
    Text: <strong>bold</strong>, <em>italic</em>, <a href="#!">linked</a>, <code>code</code>, <kbd>kbd</kbd>, <small>small</small>, super<sup>script</sup>, sub<sub>script</sub>.
  </p>
{% endset %}

// Pass content to the component and set proper HTML tag
{% include '@bolt-elements-article/article.twig' with {
  content: article_content,
  tag: 'article',
} only %}
HTML
<article class="e-bolt-article">
  <h1>
    H1 heading text
  </h1>
  <h2>
    H2 heading text
  </h2>
  <h3>
    H3 heading text
  </h3>
  <h4>
    H4 heading text
  </h4>
  <h5>
    H5 heading text
  </h5>
  <h6>
    H6 heading text
  </h6>
  <p>
    Text: <strong>bold</strong>, <em>italic</em>, <a href="#!">linked</a>, <code>code</code>, <kbd>kbd</kbd>, <small>small</small>, super<sup>script</sup>, sub<sub>script</sub>.
  </p>
</article>

button docs

Button

A graphical element that indicates interactivity.

Published Last updated: 5.0.0 Change log Github NPM
Twig Usage
{% include '@bolt-elements-button/button.twig' with {
  content: 'This is a button',
  attributes: {
    type: 'submit'
  }
} 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
content *

Content of the button.

any
icon_before

Append an icon before the button content. Icon element is recommended. However, <img> elements are also acceptable.

any
icon_after

Append an icon after the button content. Icon element is recommended. However, <img> elements are also acceptable.

any
icon_only

Append an icon to the button content and visually hide the text content. This prop trumps icon_before and icon_after.

any
hierarchy

Style the button appropriately based on information hierarchy.

string primary
  • primary, secondary, tertiary, transparent
size

Control the font-size and padding of the button.

string medium
  • xsmall, small, medium, large
border_radius

Control the border radius of the button.

string small
  • small, large, full
display

Control the display of the button.

string inline
  • inline, block, inline@from-small
Install Install
npm install @bolt/elements-button
Dependencies @bolt/core-v3.x

button

Basic Button A button is generally an inline interactive graphical element. Its main purpose is to help the user perform a function (sometimes navigate). <button class="e-bolt-button"> is acceptable at rendering a button, though the Twig template is the recommended usage for Drupal. Important Notes: Only text should be passed to the content prop. However, <span>, <em>, and <strong> elements can be used. Button element is a replacement for the Button component. Demo
Light
Dark
Twig
{% include '@bolt-elements-button/button.twig' with {
  content: 'This is a button',
  attributes: {
    type: 'button'
  }
} only %}
HTML
<button type="button" class="e-bolt-button">This is a button</button>

button attributes

HTML Attributes for Button Depending on if the <a> element or the <button> element is being used, the proper HTML attributes should be passed. Important Notes: <a> requires the href attribute. <button> requires the type attribute. Demo This button has the "href", "target", "rel", and "id" attributes
Twig
// <button>
{% include '@bolt-elements-button/button.twig' with {
  content: 'This button has the "type" attribute',
  attributes: {
    type: 'submit',
  }
} only %}

// <a>
{% include '@bolt-elements-button/button.twig' with {
  content: 'This button has the "href", "target", and "id" attributes',
  attributes: {
    href: 'https://google.com',
    target: '_blank',
    rel: 'noopener',
    id: 'js-bolt-some-unique-id'
  }
} only %}
HTML
<a href="https://google.com" target="_blank" rel="noopener" id="js-bolt-some-unique-id" class="e-bolt-button">This button has the "href", "target", "rel", and "id" attributes</a>

button with icon

Button with Icon Icons can be used in tandem with a button. An icon can be placed before and/or after the button text. The icon component is recommended for appending icons. However, an <img> element is also acceptable. Important Notes: Icons are set inline with text so icon size will grow or shrink with text size. The size and background props for the icon component are not well supported in this scenario. When writing in plain HTML, all white space must be eliminated to have the icon display correctly next to text (in terms of spacing and wrapping). The markup must be written all in one line and spaces between HTML elements must be removed. When writing in plain HTML, <span class="e-bolt-button__icon-before"> and <span class="e-bolt-button__icon-after"> are required to wrap around the icon markup. The wrapper ensures that the icon will always wrap with the final word of the text. It will never wrap to the next line on its own. Demo

Twig
// Icon vars
{% set icon_custom %}
  <img src="/images/placeholders/500x500.jpg">
{% endset %}
{% set icon_chevron_down %}
  {% include '@bolt-elements-icon/icon.twig' with {
    name: 'chevron-down',
  } only %}
{% endset %}

// Button include
{% include '@bolt-elements-button/button.twig' with {
  content: 'This is a button with icons before and after',
  icon_before: icon_custom,
  icon_after: icon_chevron_down,
  attributes: {
    type: 'button'
  }
} only %}
HTML
<button type="button" class="e-bolt-button"><span class="e-bolt-button__icon-before"><!-- Icon or image markup --></span>This is a button with icons before and after<span class="e-bolt-button__icon-after"><!-- Icon or image markup --></span></button>

button with icon only

Icon Only Button Icon only button visually hides the text content of the button. Such a button should be used sparingly and only in places where screen real estate is a concern. Important Notes: It is recommended that icon only buttons to be used in tandem with tooltip to give the user more context about the button’s function. When writing in plain HTML, aria-label is required to render the button text. For example: <button type="button" class="e-bolt-button e-bolt-button--icon-only" aria-label="Download">. Text should not be used inside the button when using aria-label. When writing in plain HTML, <span class="e-bolt-button__icon-center"> is required to wrap around the icon markup. The wrapper ensures that the icon will always center within the button. Demo File size: 25MB Add another row
Twig
// Icon only button combined with tooltip
{% set icon_download %}
  {% include '@bolt-elements-icon/icon.twig' with {
    name: 'download',
  } only %}
{% endset %}
{% set tooltip_trigger %}
  {% include '@bolt-elements-button/button.twig' with {
    content: 'Download',
    icon_only: icon_download,
    attributes: {
      type: 'button'
    }
  } only %}
{% endset %}
{% include '@bolt-components-tooltip/tooltip.twig' with {
  trigger: tooltip_trigger,
  content: 'File size: 25MB',
} only %}
HTML
// Icon only button combined with tooltip
<bolt-tooltip>
  <button type="button" class="e-bolt-button e-bolt-button--icon-only" aria-label="Download">
    <span class="e-bolt-button__icon-center"><!-- Icon or image markup --></span>
  </button>
  <span slot="content">File size: 25MB</span>
</bolt-tooltip>

button hierarchy

Button Hierarchy A button can be assigned to various levels of the content hierarchy based on the information architecture of the layout. Important Notes: Transparent button is the lowest in the hierarchy level. This style has the lowest affordances and it should NEVER be used alone. Always pair it with a primary, secondary, or tertiary button. Demo
Light
Dark
Twig
{% include '@bolt-elements-button/button.twig' with {
  content: 'This is a secondary button',
  hierarchy: 'secondary',
  attributes: {
    type: 'button'
  }
} only %}
HTML
<button type="button" class="e-bolt-button e-bolt-button--secondary">This is a secondary button</button>

button size

Button Size A button’s size can be modified per use case. Demo
Twig
{% include '@bolt-elements-button/button.twig' with {
  content: 'This is a small button',
  size: 'small',
  attributes: {
    type: 'button'
  }
} only %}
HTML
<button type="button" class="e-bolt-button e-bolt-button--small">This is a small button</button>

button border radius

Button Border Radius Rounded buttons are possible with the border_radius prop. Demo
Twig
{% include '@bolt-elements-button/button.twig' with {
  content: 'This is a fully rounded button',
  border_radius: 'full',
  attributes: {
    type: 'button'
  }
} only %}
HTML
<button type="button" class="e-bolt-button e-bolt-button--border-radius-full">This is a fully rounded button</button>

button display

Button Display The display of a button can be changed from inline to block (full width), and there is an extra option to make it transform from inline to block at the small breakpoint. Important Notes: When display prop is set to inline@from-small, it means the button is block display below the small breakpoint, and transform to inline display from small breakpoint and up. Resize the browser to see the demo below. Demo
Twig
{% include '@bolt-elements-button/button.twig' with {
  content: 'This is a full width button',
  display: 'block',
  attributes: {
    type: 'button'
  }
} only %}
HTML
<button type="button" class="e-bolt-button e-bolt-button--block">This is a full width button</button>

button upload

Upload Button The button classes can also be used on a file input. Important Notes: This is an advanced use case and the Twig template does not support this. Hierarchy should be set to tertiary. Size should be set to small. Demo
Twig
Not available in Twig. Please use plain HTML.
HTML
<input id="unique-file-id" type="file" class="e-bolt-button e-bolt-button--small e-bolt-button--tertiary">

icon docs

Icon

Inline SVG icon system.

Published Last updated: 5.0.1 Change log Github NPM
Twig Usage
{% include '@bolt-elements-icon/icon.twig' with {
  name: 'bell-solid',
} 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
name

Name of Icon

string
  • add-circle, add-solid, add, agile, app-development, arrow-left, bar-chart-circle, bar-chart, bell-solid, bolt-logo-colored, briefcase, bullseye, calendar, certification, check-circle, check-solid, check, chevron-down, chevron-left, chevron-right, chevron-up, clock-circle, close-circle, close-solid, close, cloud, co-browse, collaboration, communications, copy-to-clipboard, credit-card, cube, customer-decision-hub, customer-onboarding, customer-service, data-integrations, documentation, dollar-circle, download, email, energy, entertainment, exclamation, external-link, eye-off, eye, face-happy, face-sad, facebook-solid, facebook, filter, financial, flag-solid, full-screen-off, full-screen-on, github, globe-circle, globe, government, grid, heart-solid, heart, hospitality, ideas, industries, info-circle, info-solid, insurance, integration, intelligent-virtual-assistant, interactive, java, knowledgebase, life-sciences, link, linkedin-solid, linkedin, list, lock-solid, lock, manufacturing, map-pin-solid, map-pin, media, menu, meteor, minus-circle, minus-solid, minus, mobility, molecule, more, omni-channel, orbit, partners, pega-announce, pega-building-complex, pega-cart, pega-catalyst, pega-chat-question, pega-chat-typing, pega-chat, pega-compass, pega-connection-hierarchy, pega-database, pega-disability, pega-download-pdf, pega-heath-shield, pega-instructor, pega-map, pega-network, pega-phone-call, pega-pie-chart, pega-pin, pega-plane, pega-process-fabric, pega-send-submit, pega-setting, pega-shuffle, pega-thumbs-up, pega-timer, pega-wifi, pencil, picture, platform, podcast, presentation, print, product-delivery, refresh, reply, reporting, retail, ribbon, robo-auto, rocket, sales-automation, scalability, search, share, speed-dial, star-solid, support, system-admin, text-align-left, transportation, trash, triangle, truck, twitter-solid, twitter, unlock, upload, user-interface, user, video, warning, watch, workforce-intelligence, youtube-solid
custom_icon_path

Full source path to the custom icon.

string
size

Set icon size. If size is not set, the icon size will default to text size.

string
  • small, medium, large, xlarge
color

Set the icon color. If color is not set, the icon will default to text color.

string
  • teal, navy, yellow, orange, pink, berry, wine, violet
Install Install
npm install @bolt/elements-icon
Dependencies @bolt/core-v3.x svgson

icon

Basic Icon An Icon is an inline SVG element. <svg class="e-bolt-icon"> is acceptable at rendering an icon, though the Twig template is the recommended usage for Drupal. Important Notes: Icon element is a replacement for the Icon component. When writing inline SVG manually using <svg> HTML element, be sure to minifiy the SVG, add the element class class="e-bolt-icon", and add the attribute aria-hidden="true". Icon element can be used in tandem with Shape element to create a square or circle container around the icon. In such scenario, size and color should not be set on the Icon, they should be set on the Shape instead. Demo
Light Brand Icons
pega-announce
pega-building-complex
pega-cart
pega-catalyst
pega-chat-question
pega-chat-typing
pega-chat
pega-compass
pega-connection-hierarchy
pega-database
pega-disability
pega-download-pdf
pega-heath-shield
pega-instructor
pega-map
pega-network
pega-phone-call
pega-pie-chart
pega-pin
pega-plane
pega-process-fabric
pega-send-submit
pega-setting
pega-shuffle
pega-thumbs-up
pega-timer
pega-wifi
Other Icons
add-circle
add-solid
add
agile
app-development
arrow-left
bar-chart-circle
bar-chart
bell-solid
bolt-logo-colored
briefcase
bullseye
calendar
certification
check-circle
check-solid
check
chevron-down
chevron-left
chevron-right
chevron-up
clock-circle
close-circle
close-solid
close
cloud
co-browse
collaboration
communications
copy-to-clipboard
credit-card
cube
customer-decision-hub
customer-onboarding
customer-service
data-integrations
documentation
dollar-circle
download
email
energy
entertainment
exclamation
external-link
eye-off
eye
face-happy
face-sad
facebook-solid
facebook
filter
financial
flag-solid
full-screen-off
full-screen-on
github
globe-circle
globe
government
grid
heart-solid
heart
hospitality
ideas
industries
info-circle
info-solid
insurance
integration
intelligent-virtual-assistant
interactive
java
knowledgebase
life-sciences
link
linkedin-solid
linkedin
list
lock-solid
lock
manufacturing
map-pin-solid
map-pin
media
menu
meteor
minus-circle
minus-solid
minus
mobility
molecule
more
omni-channel
orbit
partners
pencil
picture
platform
podcast
presentation
print
product-delivery
refresh
reply
reporting
retail
ribbon
robo-auto
rocket
sales-automation
scalability
search
share
speed-dial
star-solid
support
system-admin
text-align-left
transportation
trash
triangle
truck
twitter-solid
twitter
unlock
upload
user-interface
user
video
warning
watch
workforce-intelligence
youtube-solid
Dark Brand Icons
pega-announce
pega-building-complex
pega-cart
pega-catalyst
pega-chat-question
pega-chat-typing
pega-chat
pega-compass
pega-connection-hierarchy
pega-database
pega-disability
pega-download-pdf
pega-heath-shield
pega-instructor
pega-map
pega-network
pega-phone-call
pega-pie-chart
pega-pin
pega-plane
pega-process-fabric
pega-send-submit
pega-setting
pega-shuffle
pega-thumbs-up
pega-timer
pega-wifi
Other Icons
add-circle
add-solid
add
agile
app-development
arrow-left
bar-chart-circle
bar-chart
bell-solid
bolt-logo-colored
briefcase
bullseye
calendar
certification
check-circle
check-solid
check
chevron-down
chevron-left
chevron-right
chevron-up
clock-circle
close-circle
close-solid
close
cloud
co-browse
collaboration
communications
copy-to-clipboard
credit-card
cube
customer-decision-hub
customer-onboarding
customer-service
data-integrations
documentation
dollar-circle
download
email
energy
entertainment
exclamation
external-link
eye-off
eye
face-happy
face-sad
facebook-solid
facebook
filter
financial
flag-solid
full-screen-off
full-screen-on
github
globe-circle
globe
government
grid
heart-solid
heart
hospitality
ideas
industries
info-circle
info-solid
insurance
integration
intelligent-virtual-assistant
interactive
java
knowledgebase
life-sciences
link
linkedin-solid
linkedin
list
lock-solid
lock
manufacturing
map-pin-solid
map-pin
media
menu
meteor
minus-circle
minus-solid
minus
mobility
molecule
more
omni-channel
orbit
partners
pencil
picture
platform
podcast
presentation
print
product-delivery
refresh
reply
reporting
retail
ribbon
robo-auto
rocket
sales-automation
scalability
search
share
speed-dial
star-solid
support
system-admin
text-align-left
transportation
trash
triangle
truck
twitter-solid
twitter
unlock
upload
user-interface
user
video
warning
watch
workforce-intelligence
youtube-solid
Twig
{% include '@bolt-elements-icon/icon.twig' with {
  name: 'bell-solid',
} only %}
HTML
<svg class="e-bolt-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" aria-hidden="true">...</svg>

icon size

Icon Size A Icon’s size can be modified per use case. Important Notes: Reference the schema for all options. Again, Icon element can be used in tandem with Shape element to create a square or circle container around the icon. In such scenario, size and color should not be set on the Icon, they should be set on the Shape instead. Demo
Twig
{% include '@bolt-elements-icon/icon.twig' with {
  size: 'xlarge',
  ...
} only %}
HTML
<svg class="e-bolt-icon e-bolt-icon--xlarge" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" aria-hidden="true">...</svg>

icon color

Icon Color A Icon’s color can be modified per use case. Important Notes: Reference the schema for all options. Additionally, a CSS custom property is available to change the icon color to any brand color. Define --e-bolt-icon-color inline style rule to set the desired color. Reference Color Tokens for all available brand colors. Again, Icon element can be used in tandem with Shape element to create a square or circle container around the icon. In such scenario, size and color should not be set on the Icon, they should be set on the Shape instead. Demo
Twig
{% include '@bolt-elements-icon/icon.twig' with {
  color: 'navy',
  ...
} only %}
HTML
<svg class="e-bolt-icon e-bolt-icon--navy" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" aria-hidden="true">...</svg>

icon use case custom svg

Icon Use Case: Custom SVG Custom SVG can be used instead to render an icon that is not available in the design system. Important Notes: When creating a custom SVG, start with a 32px by 32px artboard in the design tool (Adobe Illustrator, Sketch, etc.). Make sure all layers have been converted to objects, meaning there is no stroke, only shapes with color fill. Combine all objects if they visually connect (i.e. create one big shape). Set the object’s fill color to #151619. Set the widest side to 32px and center the icon within the artboard. Save the SVG and then use imgoptim or another tool to minify it. Lastly: If you choose Twig usage: Add the relevant attributes {{ attributes.addClass(classes)|without('aria-hidden') }} aria-hidden="true" to the <svg> HTML element and save it as a Twig file. Then you can display the icon using include statement by passing the icon source path to the custom_icon_path prop. If you choose HTML usage: Add class="e-bolt-icon" along with relevant modifier class for each prop, and the attribute aria-hidden="true" to the <svg> HTML element. Then you can display the icon using the modified <svg> markup. Demo
Twig
{% include '@bolt-elements-icon/icon.twig' with {
  custom_icon_path: 'full/path/to/custom-icon-file.twig',
} only %}
HTML
<svg class="e-bolt-icon e-bolt-icon--xlarge e-bolt-icon--orange" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" aria-hidden="true"><path fill="#151619" d="m32 16c0 8.8-7.2 16-16 16s-16-7.2-16-16 7.2-16 16-16 16 7.2 16 16zm-3.1 0-1.7 1.4-4-3.8 1.1-5.4 2.2.2c-1.6-2.2-3.9-3.9-6.5-4.7l.9 2.1-4.9 2.7-4.8-2.7.8-2.1c-2.6.9-4.8 2.5-6.5 4.7l2.2-.2 1 5.4-4 3.8-1.6-1.4c0 2.8.9 5.4 2.5 7.6l.5-2.2 5.5.7 2.3 5-1.9 1.2c2.6.8 5.4.8 8 0l-1.9-1.1 2.3-5 5.5-.7.5 2.2c1.6-2.3 2.5-4.9 2.5-7.7zm-16 4.5-1.9-5.9 5-3.6 5 3.6-1.9 5.9z"/></svg>

image docs

Image

A responsive image embed.

Published Last updated: 5.1.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>
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>

printable docs

Printable

An media container that styles children HTML elements for print.

Published Last updated: 5.1.0 Change log Github NPM
Install Install
npm install @bolt/elements-printable
Dependencies @bolt/core-v3.x

printable

Basic Printable A Printable element can be used for any content you wish to be visible and styled in print mode. Important Notes: You must add the e-bolt-printable class to the <body> element. It will hide everything on the page in print mode. Then add the the e-bolt-printable__article class to the article container. This class will make the article visible in print mode. Additionally, print specific styles are set for many plain HTML elements. Demo

This is an example of an element to be printed

Only the heading and this paragraph will be shown in print mode. Click “Open in new tab” to view it outside of Pattern Lab, then in the browser menu click “Print”.

Twig
Not available in Twig. Please use plain HTML.
HTML
<body class="e-bolt-printable">
  <article class="e-bolt-printable__article">
    <h2>This is an example of an article to be printed</h2>
    <p>Only the heading and this paragraph will be shown in print mode.</p>
  </article>
</body>

ratio docs

Ratio

A ratio displays an image or video embed at a specific aspect ratio.

Published Last updated: 5.1.0 Change log Github NPM
Twig Usage
{% set image %}
  {% include '@bolt-elements-image/image.twig' with {
    attributes: {
      alt: 'Alt text.',
      src: 'https://via.placeholder.com/400x300',
      width: 400,
      height: 300,
    },
  } only %}
{% endset %}
{% include '@bolt-elements-ratio/ratio.twig' with {
  content: image,
  ratio: 'wide',
} 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
content

A nested element with proportions defined through ratio property. It can be for example image or video.

any
ratio

An aspect ratio between the width and height. Expressed as width divided by height. You can choose from: standard(4/3), square(1/1), wide(16/9). Custom aspect ratio can be set via the CSS custom property --e-bolt-aspect-ratio.

string standard
  • standard, square, wide
Install Install
npm install @bolt/elements-ratio
Dependencies @bolt/core-v3.x

ratio

Basic Ratio Aspect ratio is most commonly expressed as two integers and a division sign: width / height. To measure the aspect ratio of an image or video, divide the width by the height. For example, an image or video that is 400x300 pixels and one that is 260x195 pixels have the same ratio 4/3 (standard). Important Notes: Reference the schema for all options. Use in tandem with an image: set a different aspect ratio than the image’s natural aspect ratio. This will crop the image. Do not use the Ratio element if cropping is not needed. When the image’s width is smaller than the parent container, the image will stretch to fill the available space. Use in tandem with a video: the Ratio element preserves the needed space to load a video embed, preventing Cumulative Layout Shift. Additionally, a CSS custom property is available to change the aspect ratio to anything. Define --e-bolt-aspect-ratio inline style rule to set the desired aspect ratio. Demo The ratio prop is set to standard. The aspect ratio is 4/3.
Alt text.
The ratio prop is set to square. The aspect ratio is 1/1.
Alt text.
The ratio prop is set to wide. The aspect ratio is 16/9.
Alt text.
The ratio prop is set with --e-bolt-aspect-ratio via inline CSS style. The aspect ratio is 7/3.
Alt text.
Twig
{% set image %}
  {% include '@bolt-elements-image/image.twig' with {
    attributes: {
      alt: 'Alt text.',
      src: 'https://via.placeholder.com/400x300',
      width: 200,
      height: 200,
    },
  } only %}
{% endset %}
{% include '@bolt-elements-ratio/ratio.twig' with {
  content: image,
  ratio: 'square',
} only %}
HTML
<div class="e-bolt-ratio e-bolt-ratio--square">
  <!-- image or video goes here -->
</div>

ratio video

Ratio for Videos The most common aspect ratio for videos is wide (16/9). Important Notes: A 16/9 ratio is typically seen as optimal because it is capable of the highest resolution. It is also easy to capture this aspect ratio on almost all devices. Demo
Twig
{% set video %}
  <video-js
    data-account="1900410236"
    data-player="O3FkeBiaDz"
    data-embed="default"
    data-video-id="6236693947001"
    data-media-duration
    data-media-title
    controls
    class="c-base-video"></video-js>
{% endset %}
{% include '@bolt-elements-ratio/ratio.twig' with {
  content: video,
  ratio: 'wide',
} only %}
HTML
<div class="e-bolt-ratio e-bolt-ratio--wide">
  <video-js
    data-account="1900410236"
    data-player="O3FkeBiaDz"
    data-embed="default"
    data-video-id="6236693947001"
    data-media-duration
    data-media-title
    controls
    class="c-base-video"></video-js>
</div>
Use Case: Image Fit and Position within Ratio The Image element comes with advanced position and fit options. They can work in tandem with the Ratio element. Important Notes: Reference the Image element for all options. Demo
Alt text.
Twig
{% set image %}
  {% include '@bolt-elements-image/image.twig' with {
    attributes: {
      alt: 'Alt text.',
      src: 'https://via.placeholder.com/400x250',
      width: 400,
      height: 250,
      style: '--e-bolt-image-position: top right',
    },
  } only %}
{% endset %}
{% include '@bolt-elements-ratio/ratio.twig' with {
  content: image,
  ratio: 'square',
} only %}
HTML
<div class="e-bolt-ratio e-bolt-ratio--square">
  <img src="https://via.placeholder.com/400x250" width=400 height=250 class="e-bolt-image" alt="" style="--e-bolt-image-position: top right">
</div>

shape docs

Shape

A 1:1 ratio container that displays decorative content.

Published Last updated: 5.0.0 Change log Github NPM
Twig Usage
{% include '@bolt-elements-shape/shape.twig' with {
  content: 'MM',
} 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)
content *

Content of the shape.

any
attributes

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

object
size

Changes the size of the interior element

string small
  • small, medium, large, xlarge
border_radius

Customizes the outside radius of the shape. "none" will render as a square shape, "small" and "large" will render as a rounded corners square and "full" will render as a circle.

string full
  • none, small, large, full
Install Install
npm install @bolt/elements-shape
Dependencies @bolt/core-v3.x

shape

Basic Shape A Shape is a 1:1 ratio container that displays decorative content. Important Notes: Content can be letters, icons, or images. When passing letters to the content, it can accept up to 2 letters. Demo
Light MM Alt text.
Dark MM Alt text.
Twig
{% include '@bolt-elements-shape/shape.twig' with {
  content: 'MM',
} only %}
HTML
<span class="e-bolt-shape">
  <span class="e-bolt-shape__content">
    <!-- Letters, icon, or image go here -->
  </span>
</span>

shape border radius

Shape Border Radius A Shape’s border radius can be modified to create various shapes. Important Notes: Reference the schema for all options. Demo MM MM MM MM
Twig
{% include "@bolt-elements-shape/shape.twig" with {
  border_radius: 'full',
  ...
} only %}
HTML
<span class="e-bolt-shape e-bolt-shape--border-radius-full">
  <span class="e-bolt-shape__content">
    <!-- Letters, icon, or image go here -->
  </span>
</span>

shape size

Shape Size A Shape’s size can be modified per use case. Important Notes: Reference the schema for all options. When passing letters to the content, text size scales with the shape size. When passing an icon to the content, icon size is ignored. Icon size scales with the shape size. When passing an image to the content, image size is ignored. Image size scales with the shape size. Demo MM MM MM MM
Twig
{% include '@bolt-elements-shape/shape.twig' with {
  size: 'large',
  ...
} only %}
HTML
<span class="e-bolt-shape e-bolt-shape--large">
  <span class="e-bolt-shape__content">
    <!-- Letters, icon, or image go here -->
  </span>
</span>

shape theming

Shape Theming A Shape can accept all existing themes. Important Notes: Pass a .t-bolt-* theme class to the parent element to color a shape. Reference the Theming System for all available themes. Demo
Light
  • .t-bolt-white
  • .t-bolt-black
  • .t-bolt-gray-xlight
  • .t-bolt-navy-dark
  • .t-bolt-navy
  • .t-bolt-navy-light
  • .t-bolt-teal
  • .t-bolt-yellow
  • .t-bolt-orange
  • .t-bolt-pink
  • .t-bolt-wine
  • .t-bolt-berry
  • .t-bolt-violet
Dark
  • .t-bolt-white
  • .t-bolt-black
  • .t-bolt-gray-xlight
  • .t-bolt-navy-dark
  • .t-bolt-navy
  • .t-bolt-navy-light
  • .t-bolt-teal
  • .t-bolt-yellow
  • .t-bolt-orange
  • .t-bolt-pink
  • .t-bolt-wine
  • .t-bolt-berry
  • .t-bolt-violet
Twig
{% include '@bolt-elements-shape/shape.twig' with {
  attributes: {
    class: 't-bolt-navy',
  }
  ...
} only %}
HTML
<span class="e-bolt-shape t-bolt-navy">
  <span class="t-bolt-shape__content">
    <!-- Letters, icon, or image go here -->
  </span>
</span>