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>

ratio use case fit and position

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>