Cookies on ons.gov.uk

Cookies are small files stored on your device when you visit a website. We use some essential cookies to make this website work.

We would like to set additional cookies to remember your settings and understand how you use the site. This helps us to improve our services.

View cookies

You have accepted all additional cookies. You have rejected all additional cookies. You can change your cookie preferences at any time.

Skip to main content

Image

Overview

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 (Example Image For Retina Screens)

Example Image For Retina Screens contents

Nunjucks

{% from "components/image/_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'
    })
}}

Nunjucks macro options

NameTypeRequiredDescription
urlstringtrue (unless image is set)The complete source path of the image including filename and extension
imageObject<Image>true (unless url is set)Settings for the path and filename attributes for the image
altstringfalseThe HTML alt tag used to explain the appearance and function of the image. Not required if the image is only decorative.
captionstringfalseA short visible caption describing the contents of the image
Image
NameTypeRequiredDescription
smallSrcstringtruePath to the small version of the image
largeSrcstringfalsePath to the large retina version of the image

HTML

<figure class="ons-image">
  <img class="ons-image__img"
    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-image__caption"> Image 1 - Woman in a purple dress shirt using a laptop </figcaption>
</figure>

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 (Example Image For Regular Screens)

Example Image For Regular Screens contents

Nunjucks

{% from "components/image/_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'
    })
}}

Nunjucks macro options

NameTypeRequiredDescription
urlstringtrue (unless image is set)The complete source path of the image including filename and extension
imageObject<Image>true (unless url is set)Settings for the path and filename attributes for the image
altstringfalseThe HTML alt tag used to explain the appearance and function of the image. Not required if the image is only decorative.
captionstringfalseA short visible caption describing the contents of the image
Image
NameTypeRequiredDescription
smallSrcstringtruePath to the small version of the image
largeSrcstringfalsePath to the large retina version of the image

HTML

<figure class="ons-image">
  <img class="ons-image__img" src="/img/small/woman-in-purple-dress-shirt.jpg"
    alt="Woman in a purple dress shirt using a laptop">
  <figcaption class="ons-image__caption"> Image 1 - Woman in a purple dress shirt using a laptop </figcaption>
</figure>

Help improve this foundation

Let us know how we could improve this foundation or share your user research findings. Discuss ‘Images’ on GitHub (opens in a new tab) 

Help improve this page

Let us know how we could improve this page, or share your user research findings. Discuss ‘Images’ on GitHub (opens in a new tab)