Skip to main content

Images

Adds an image to the page with an optional caption.

Improved approach for retina screens

Uses two versions of the image, one for standard screens and the other for retina screens.

We specify a folder path for both small and large images which is defined in the macro as smallSrc and largeSrc. The filename is expected to be the same for both.

If the image is decorative and does not convey important information, do not add an alt tag. This will then be hidden from screen reader users.

Open this example in a new tab  
<figure class="ons-figure">
  <img class="ons-figure__image" srcset="/img/small/woman-in-purple-dress-shirt.jpg 1x, /img/large/woman-in-purple-dress-shirt.jpg 2x" src="/img/small/woman-in-purple-dress-shirt.jpg" alt="">
  <figcaption class="ons-figure__caption">
    Image 1 - Woman in a purple dress shirt using a laptop
  </figcaption>
</figure>
{% from "components/images/_macro.njk" import onsImage %}
{{
    onsImage({
        image: {
            smallSrc: '/img/small/woman-in-purple-dress-shirt.jpg',
            largeSrc: '/img/large/woman-in-purple-dress-shirt.jpg'
        },
        caption: 'Image 1 - Woman in a purple dress shirt using a laptop'
    })
}}
Name Type Required Description
url string true (false if Image provided) The complete image path including filename and extension
image Image false (true if url not provided) An object containing path and filename attributes for the image
alt string false Alt tag to explain the appearance and function of the image
caption string false A short caption describing the contents

Image

Name Type Required Description
smallSrc string true Path to the non-retina version of the image
largeSrc string true Path to the retina version of the image 
{%- macro onsImage(params) -%}
    <figure class="ons-figure">
        
        {% if params.image is defined and params.image %}
            <img class="ons-figure__image" srcset="{{ params.image.smallSrc }} 1x, {{ params.image.largeSrc }} 2x" src="{{ params.image.smallSrc }}" alt="{{ params.alt }}">
        {% else %}
            <img class="ons-figure__image" src="{{ params.url }}" alt="{{ params.alt }}">
        {% endif %}

        {% if params.caption is defined and params.caption %}
            <figcaption class="ons-figure__caption">
                {{ params.caption }}
            </figcaption>
        {% endif %}
        
    </figure>
{%- endmacro -%}

.ons-figure {
  margin: 0;

  @extend .ons-u-mb-m;

  &__image {
    display: block;
    max-width: 100%;
  }

  &__caption {
    display: block;
    font-size: 0.8rem;
    padding: 0.5rem 0 0;
  }
}

Old approach

Specifies a single image that would appear blurry on retina displays.

This continues to use the original macro property url for the image path.

Open this example in a new tab  
<figure class="ons-figure">
  <img class="ons-figure__image" src="/img/small/woman-in-purple-dress-shirt.jpg" alt="Woman in a purple dress shirt using a laptop">
  <figcaption class="ons-figure__caption">
    Image 1 - Woman in a purple dress shirt using a laptop
  </figcaption>
</figure>
{% from "components/images/_macro.njk" import onsImage %}
{{
    onsImage({
        url: '/img/small/woman-in-purple-dress-shirt.jpg',
        alt: 'Woman in a purple dress shirt using a laptop',
        caption: 'Image 1 - Woman in a purple dress shirt using a laptop'
    })
}}
Name Type Required Description
url string true (false if Image provided) The complete image path including filename and extension
image Image false (true if url not provided) An object containing path and filename attributes for the image
alt string false Alt tag to explain the appearance and function of the image
caption string false A short caption describing the contents

Image

Name Type Required Description
smallSrc string true Path to the non-retina version of the image
largeSrc string true Path to the retina version of the image 
{%- macro onsImage(params) -%}
    <figure class="ons-figure">
        
        {% if params.image is defined and params.image %}
            <img class="ons-figure__image" srcset="{{ params.image.smallSrc }} 1x, {{ params.image.largeSrc }} 2x" src="{{ params.image.smallSrc }}" alt="{{ params.alt }}">
        {% else %}
            <img class="ons-figure__image" src="{{ params.url }}" alt="{{ params.alt }}">
        {% endif %}

        {% if params.caption is defined and params.caption %}
            <figcaption class="ons-figure__caption">
                {{ params.caption }}
            </figcaption>
        {% endif %}
        
    </figure>
{%- endmacro -%}

.ons-figure {
  margin: 0;

  @extend .ons-u-mb-m;

  &__image {
    display: block;
    max-width: 100%;
  }

  &__caption {
    display: block;
    font-size: 0.8rem;
    padding: 0.5rem 0 0;
  }
}

Help improve this foundation

Let us know how we could improve this foundation or share your user research findings. Discuss ‘Images’ on GitHub 

More in ‘Components’