Content presentation - Images

Use images only if there is a real user need. Avoid unnecessary decoration.

Open this default images example in new window
Copy default images code 
<figure class="hs2-image">
  <img class="hs2-image__img" src="https://assets.hs2.org.uk/wp-content/uploads/2022/02/HS2-VL-35279-220203_HS2_Apprentice_Curzon_NR-48-1400x631.jpeg" alt="HS2 apprentices">
  <figcaption class="hs2-image__caption">
    HS2 apprentices
  </figcaption>
</figure>
Close default images code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for default images
Name Type Required Description
Name src Type string Required true Description The source location of the image.
Name alt Type string Required true Description The alt text of the image.
Name caption Type string Required false Description Optional caption text for the image.
Name sizes Type string Required false Description A list of screen sizes for the browser to load the correct image from the srcset images.
Name srcset Type string Required false Description A list of image source URLs and their respective sizes. Separate each image with a comma.
Name classes Type string Required false Description Classes to add to the image container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the image container.
Copy default images code 
{% from 'images/macro.njk' import image %}

{{ image({
  "src": "https://assets.hs2.org.uk/wp-content/uploads/2022/02/HS2-VL-35279-220203_HS2_Apprentice_Curzon_NR-48-1400x631.jpeg",
  "alt": "HS2 apprentices",
  "caption": "HS2 apprentices"
}) }}
Close default images code

When to use images

Informative images that meet real user needs can be very important.

Users with some access needs (such as dyslexia) may navigate pages through images. Images help them orient themselves and they separate out the content.

But having unnecessary or decorative images can frustrate users, especially on information pages or transactional journeys.

How to use images

Images should flow with the text content, not appear too prominent or isolated.

We recommend stacking images as gallery views (images side by side) can confuse users.

Captions

The image component is made up of 2 elements - the image and a caption underneath it in a white box.

Not all images need captions. If you use them:

  • write a full sentence ending with a full stop
  • keep captions short – ideally 1 sentence but no more than 2
  • start the caption with a number if the images show a sequence
  • do not duplicate alt-text (alternative text)

The caption assumes that the user can either see the image or read the alt-text. Use it to explain what you want users to conclude from it.

Here's an example. The alt-text is "HS2 Apprentices". The caption explains that HS2 offers a variety of apprenticeships

HS2 Apprentices
1. HS2 has a variety of apprenticeship schemes on offer for young people

Accessibility

Do not use images that have words in them, because screen readers will not be able to read the words.

Alternative text (alt-text)

Images must have text alternatives that describe the information or function they represent. This makes sure that people with disabilities can understand them.

When using an image (or the img element), specify a text alternative with the alt attribute.

Alt-text is not usually visible but is read out by screen readers or displayed if an image does not load or if images have been switched off.

Read more about alt-text in the guidance on using alt-text for images in content.

Long descriptions

With complex images long descriptions help people who face barriers due to sight loss.