background docs

Background

An absolute positioned element that renders as a background (image, video, or shapes) inside relative positioned containers.
Twig Usage 
{% set image %}
    {% include '@bolt-elements-image/image.twig' with {
      background: true,
      attributes: {
        src: '/images/placeholders/backgrounds/background-light-tall.jpg',
        srcset: '/images/placeholders/backgrounds/background-light-tall-640.jpg 640w, /images/placeholders/backgrounds/background-light-tall-1024.jpg 1024w, /images/placeholders/backgrounds/background-light-tall-1920.jpg 1920w',
        width: 3840,
        height: 2160,
      },
    } only %}
  {% endset %}
  <div style="height: 400px; position: relative;" class="t-bolt-black">
    {% include '@bolt-components-background/background.twig' with {
      fill: 'gradient',
      items: [
        image,
      ]
    } only %}
  </div>
 Schema
Prop Name Description Type Default Value Option(s)
attributes

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

 object —
  • —
opacity

Overlay opacity

 string none
  • none, light, medium, heavy, full
fill

Type of fill to use for the overlay.

 string solid
  • solid or gradient
focal_point

Point where the background gradient highlight should originate.

 object —
    • horizontal

      X-axis positioning for the background focal point

      • center, left, right
    • vertical

      Y-axis positioning for the background focal point

      • center, top, bottom
video

Set to true if you like to use video as a background.

 boolean false
  • —
video_toggle_button

A Drupal-rendered button that will play and pause a background video.

 any —
  • —
items

An array of renderable items to place in the background.

 array —
  • [items]:
    • Type:any
shape_group

Add a Bolt Background Shapes group.

 string none
  • A, B, none
shape_alignment

Alignment of shape group.

 string right
  • left or right
Install Install 
npm install @bolt/components-background
Dependencies @bolt/components-background-shapes @bolt/core @bolt/elements-image

background

Background Component Basic Usage Example of a default Background Component.
Important Notes: When adding an image to the Background Component always consider the contrast ratio between the foreground text and background image. The Background Component has a couple of options to add contrast, the Opacity prop, the Fill prop and the Gradient Utility class. Please refer to the documentation for more information.
Demo
Alt text.

Visualization & Simulation

Imagine the Future with Decision Hub

Continuously improve results by visualizing how future adjustments to your strategies can impact business performance. Simulate and test your ideas, evaluate the results using intuitive views, and then deploy optimal alterations.
Twig
{% include '@bolt-components-background/background.twig' with {
  opacity: 'medium',
  items: [
    image
  ]
} only %}
HTML
Not available in plain HTML. Please use Twig.

background valign

Background Component with a Valign Examples of a Background Component with the different valign options.
Important Notes: Alignment of an background image can be achieved by leveraging the Image Element's attributes prop with the a CSS var. Please refer to the fit and position documentation for more information.
Demo

Background Component with an image vertically centered

Visualization & Simulation

Imagine the Future with Decision Hub

Continuously improve results by visualizing how future adjustments to your strategies can impact business performance. Simulate and test your ideas, evaluate the results using intuitive views, and then deploy optimal alterations.

Background Component with an image vertically aligned to top

Visualization & Simulation

Imagine the Future with Decision Hub

Continuously improve results by visualizing how future adjustments to your strategies can impact business performance. Simulate and test your ideas, evaluate the results using intuitive views, and then deploy optimal alterations.

Background Component with an image vertically aligned to bottom

Visualization & Simulation

Imagine the Future with Decision Hub

Continuously improve results by visualizing how future adjustments to your strategies can impact business performance. Simulate and test your ideas, evaluate the results using intuitive views, and then deploy optimal alterations.

Background Component with an image vertically aligned 25% from top

Visualization & Simulation

Imagine the Future with Decision Hub

Continuously improve results by visualizing how future adjustments to your strategies can impact business performance. Simulate and test your ideas, evaluate the results using intuitive views, and then deploy optimal alterations.
Twig
{% set image %}
  {% include '@bolt-elements-image/image.twig' with {
    background: true,
    attributes: {
      src: '/images/placeholders/backgrounds/background-light-tall.jpg',
      srcset: '/images/placeholders/backgrounds/background-light-tall-640.jpg 640w, /images/placeholders/backgrounds/background-light-tall-1024.jpg 1024w, /images/placeholders/backgrounds/background-light-tall-1920.jpg 1920w',
      width: 4320,
      height: 2880,
      style: '--e-bolt-image-position: center center;',
    },
  } only %}
{% endset %}

{% include '@bolt-components-background/background.twig' with {
  opacity: 'medium',
  items: [
    image
  ]
} only %}
HTML
Not available in plain HTML. Please use Twig.

background video

Background Video Background Video should be used only for decorative purposes.
Important Notes: Set video boolean prop to true when you want to render a background video. When creating the video element, it is required to make sure the controls attribute is not present. In addition, make sure the following attributes are present on the video element; autoplay, loop, and muted. Consider this video as decoration and not content (limit elements like words, prominant faces, or brand marks from the video), expect it to be cropped at some point. By design, the background video will disappear when the device witdth is below 800px (this is for visible stablity on smaller screens). The background video should be nested inside the Ratio Element, refer to the Ratio Element docs for more information. Provide a poster background image as a fallback. This will be displayed when the video is being loaded and smaller screen sizes, refer to the Background Image Element docs for more information. The background video play or pause toggle button will be displayed based on logic in the Background Component Drupal module.
Demo

Visualization & Simulation

Imagine the Future with Decision Hub

Continuously improve results by visualizing how future adjustments to your strategies can impact business performance. Simulate and test your ideas, evaluate the results using intuitive views, and then deploy optimal alterations.
Twig
{% set toggle_button %}
  {% set icon_video %}
    <svg class="e-bolt-icon" viewBox="0 0 36 36" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
      <path d="M 11 10 L 17 10 L 17 26 L 11 26 M 20 10 L 26 10 L 26 26 L 20 26">
        <animate class="background-video-toggle-animation" begin="indefinite" attributeType="XML" attributeName="d" fill="freeze" from="M11,10 L17,10 17,26 11,26 M20,10 L26,10 26,26 20,26" to="M11,10 L18,13.74 18,22.28 11,26 M18,13.74 L26,18 26,18 18,22.28" dur="0.1s" keySplines=".4 0 1 1"
        repeatCount="1"></animate>
      </path>
  </svg>
  {% endset %}

  {% include '@bolt-elements-button/button.twig' with {
    content: 'Pause',
    icon_only: icon_video,
    border_radius: 'full',
    hierarchy: 'secondary',
    attributes: {
      type: 'button',
      'data-video-target': 'backgroundVideoTarget',
      class: 'js-base-video-toggle js-bolt-background-video-toggle c-bolt-background__video-toggle-button is-playing',
      'aria-label': 'Pause the background video'
    }
  } only %}
{% endset %}
{% set background_video %}
  {% include '@bolt-elements-image/image.twig' with {
    attributes: {
      src: '/images/placeholders/backgrounds/background-light-tall.jpg',
      background: true,
      loading: 'lazy',
    }
  } only %}
  {% set video %}
    <video-js
      data-account="1900410236"
      data-player="O3FkeBiaDz"
      data-embed="default"
      data-video-id="5999324539001"
      autoplay loop muted
      id="backgroundVideoTarget"
      class="c-base-video"></video-js>
  {% endset %}
  {% include '@bolt-elements-ratio/ratio.twig' with {
    content: video,
    ratio: 'wide'
  } only %}
{% endset %}
{% include './_00-background-band-demo.twig' with {
  background: {
    fill: 'solid',
    video: true,
    video_toggle_button: toggle_button,
    opacity: 'heavy',
    items: [
      background_video,
    ]
  }
} only %}
HTML
Not available in plain HTML. Please use Twig.

background shapes

Background Component with Background Shapes Examples of a Background Component with Background Shapes and Background Alignment.
Important Notes: The shape_group and shape_alignemnt props are deprecated and are no longer supported. Please don't use them.
Demo

Example of a Background Shape "A"

circle-square
Outline Circle
square-square
Little Circle
square-square
Little Circle

Visualization & Simulation

Imagine the Future with Decision Hub

Continuously improve results by visualizing how future adjustments to your strategies can impact business performance. Simulate and test your ideas, evaluate the results using intuitive views, and then deploy optimal alterations.

Example of a Background Shape "B"

square-square
Outline Circle
square-square
Little Circle
circle-circle
Outline Circle

Visualization & Simulation

Imagine the Future with Decision Hub

Continuously improve results by visualizing how future adjustments to your strategies can impact business performance. Simulate and test your ideas, evaluate the results using intuitive views, and then deploy optimal alterations.

Example of a Background Shape "A" with Shape Alignment Left

circle-square
Outline Circle
square-square
Little Circle
square-square
Little Circle

Visualization & Simulation

Imagine the Future with Decision Hub

Continuously improve results by visualizing how future adjustments to your strategies can impact business performance. Simulate and test your ideas, evaluate the results using intuitive views, and then deploy optimal alterations.
Twig
{% include '@bolt-components-background/background.twig' with {
  shape_group: 'A',
  shape_alignment: 'left'
} only %}
HTML
Not available in plain HTML. Please use Twig.

background theme compatibility

Theme Background inherits its theme from the closest parent element with a theming class.
Important Notes: The background component does not have a theme prop. Theme is instead determined by a t-bolt-* class on the nearest parent element. Theme affects both background color and text, buttons, etc. For this reason, do not add a t-bolt-* class to the background itself, but rather a parent element that is also a parent of any overlaid text. Accessibility may vary with gradient fills or opacity less than full. Use the focal_point prop, text positioning, and good judgment in these scenarios.
Demo

All themes are supported. A few examples are shown below.

Alt text.
White Theme

This background has a solid fill and the surrounding theme is t-bolt-white
Alt text.
Black Theme

This background has a solid fill and the surrounding theme is t-bolt-black
Alt text.
Dark Navy Theme

This background has a solid fill and the surrounding theme is t-bolt-navy-dark
Twig
<div class="t-bolt-navy-dark">
  {% include '@bolt-components-background/background.twig' with {
    fill: 'solid',
  } only %}
</div>
HTML
Not available in plain HTML. Please use Twig.

background focal point

Focal Point focal_point sets the horizontal and vertical alignment of the gradient (if applicable).
Important Notes: The coordinates of the point represent the lightest or most transparent part of the gradient. Use this prop to make overlayed text more readible or change the point of interest in background colors and/or image. Focal point only makes sense with gradients. It has no effect on solid backgrounds.
Demo
This background has a gradient fill and the focal point is set to horiztonal: left and vertical: top
This background has a gradient fill and the focal point is set to horiztonal: left and vertical: bottom
Twig
{% include '@bolt-components-background/background.twig' with {
  fill: 'gradient',
  focal_point: {
    vertical: 'top',
    horizontal: 'left',
  },
} only %}
HTML
Not available in plain HTML. Please use Twig.

background fill

Background Component with a Fill Examples of a Background Component with the solid and gradient fill options.
Important Notes: When using the fill prop consider using an opacity prop as well. For more information on the opacity prop, reference the Background Opacity documentation.
Demo

Background Component with Solid Fill

Visualization & Simulation

Imagine the Future with Decision Hub

Continuously improve results by visualizing how future adjustments to your strategies can impact business performance. Simulate and test your ideas, evaluate the results using intuitive views, and then deploy optimal alterations.

Background Component with Gradient Fill

Visualization & Simulation

Imagine the Future with Decision Hub

Continuously improve results by visualizing how future adjustments to your strategies can impact business performance. Simulate and test your ideas, evaluate the results using intuitive views, and then deploy optimal alterations.
Twig
{% set image %}
  {% include '@bolt-elements-image/image.twig' with {
    background: true,
    attributes: {
      src: '/images/placeholders/backgrounds/background-light-tall.jpg',
      srcset: '/images/placeholders/backgrounds/background-light-tall-640.jpg 640w, /images/placeholders/backgrounds/background-light-tall-1024.jpg 1024w, /images/placeholders/backgrounds/background-light-tall-1920.jpg 1920w',
      width: 4320,
      height: 2880
    },
  } only %}
{% endset %}

{% include '@bolt-components-background/background.twig' with {
  fill: 'solid',
  opacity: 'medium',
  items: [
    image
  ]
} only %}
HTML
Not available in plain HTML. Please use Twig.

background opacity

Background Component with Opacity Examples of a Background Component with Opacity options.
Important Notes: The default opacity color is the brand navy color.
Demo

Example of a Background Component with opacity: none

Alt text.

Visualization & Simulation

Imagine the Future with Decision Hub

Continuously improve results by visualizing how future adjustments to your strategies can impact business performance. Simulate and test your ideas, evaluate the results using intuitive views, and then deploy optimal alterations.

Example of a Background Component with opacity: light

Alt text.

Visualization & Simulation

Imagine the Future with Decision Hub

Continuously improve results by visualizing how future adjustments to your strategies can impact business performance. Simulate and test your ideas, evaluate the results using intuitive views, and then deploy optimal alterations.

Example of a Background Component with opacity: medium

Alt text.

Visualization & Simulation

Imagine the Future with Decision Hub

Continuously improve results by visualizing how future adjustments to your strategies can impact business performance. Simulate and test your ideas, evaluate the results using intuitive views, and then deploy optimal alterations.

Example of a Background Component with opacity: heavy

Alt text.

Visualization & Simulation

Imagine the Future with Decision Hub

Continuously improve results by visualizing how future adjustments to your strategies can impact business performance. Simulate and test your ideas, evaluate the results using intuitive views, and then deploy optimal alterations.

Example of a Background Component with opacity: full

Alt text.

Visualization & Simulation

Imagine the Future with Decision Hub

Continuously improve results by visualizing how future adjustments to your strategies can impact business performance. Simulate and test your ideas, evaluate the results using intuitive views, and then deploy optimal alterations.
Twig
{% include '@bolt-components-background/background.twig' with {
  opacity: 'medium',
  items: [
    image
  ]
} only %}
HTML
Not available in plain HTML. Please use Twig.

background use case hero

Background Component Use Case Hero This is an example of a Background Component with an image being used as a hero section.
Important Notes: Any images at the top of the page, or in the hero section, should have loading set to eager.
Demo

Visualization & Simulation

Imagine the Future with Decision Hub

Continuously improve results by visualizing how future adjustments to your strategies can impact business performance. Simulate and test your ideas, evaluate the results using intuitive views, and then deploy optimal alterations.
Twig
{% set image %}
  {% include '@bolt-elements-image/image.twig' with {
    background: true,
    attributes: {
      src: '/images/placeholders/backgrounds/background-light-tall.jpg',
      loading: 'eager'
    },
  } only %}
{% endset %}
{% include '@bolt-components-background/background.twig' with {
  opacity: 'heavy',
  fill: 'gradient',
  focal_point: {
    horizontal: 'right',
    vertical: 'top',
  },
  items: [
    image,
  ]
} only %}
HTML
Not available in plain HTML. Please use Twig.