Image

Photos, Vectors, Illustrations and other imagery

Example

Open example in a new window

Code sample

<picture>
  <source srcset="https://placehold.co/900x900/000000/fffffff/webp" media="(min-resolution: 3x)">
  <img width="300" height="300" src="https://placehold.co/600x600/000000/fffffff/webp" alt>
</picture>

Notes

  • All image elements (<img>) need alt attributes.
  • If the image is informational, i.e. it is part of the content of the document, and is strictly non-decorational, then give the alt attribute an appropriate value (alternate text representation for the image). A good rule of thumb here: Explain what you're seeing in the image.
  • If the image is typically 'below the fold', then apply the loading="lazy" attribute.
  • If the image has an intrinsic or natural size within the content and won't be responsive, then specify this using the width and height attributes.
  • By default, you should be serving an image that is twice the size of the dimensions specified in the width and height attributes, since most devices have pixel densities greater than 2x.
  • Provide a higher-resolution <source> and use an appropriate media query. This media query could be a viewport width query if the image is responsive, or a higher-resolution query.
  • Use optimised WebP images rather than JPGs, GIFs, or PNGs. Use something like squoosh.app to help convert any images to WebP.

Details

Pattern scope:
Atom – The smallest possible pattern, independent
Relevant assets:
Stylesheets:

Variants

  • Scheme: Profile 

    The image is a photo of a person, and typically associated with their profile. Turn the square image into a circle, and use a thick border.

    Example

    Open type in a new window

    Code sample

    <figure data-scheme="profile">
  <picture>
    <source srcset="https://placehold.co/720x720/eeeeee/111111/webp" media="(min-resolution: 3x)">
    <img width="240" height="240" src="https://placehold.co/480x480/eeeeee/111111/webp" alt>
  </picture>
  <figcaption>
    <p><b>Gavin Rossdale</b></p>
    <p>Balthazar, Constantine</p>
  </figcaption>
</figure>

    Notes

    • Use the attribute: data-scheme="profile".
    • Only square images can be used here
    • Wrap the <picture> in a <figure> and (optionally) supply their name/title in a <figcaption>.
  • Scheme: Soften 

    The image needs a softening treatment. Subtle borders, and a light border radius are applied.

    Example

    Open type in a new window

    Code sample

    <picture data-scheme="soften">
  <source srcset="https://placehold.co/900x600/ffffff/333333/webp" media="(min-resolution: 3x)">
  <img width="300" height="200" src="https://placehold.co/600x400/ffffff/333333/webp" alt>
</picture>

    Notes

    Use the attribute: data-scheme="soften".

  • Image Lightbox 

    The image is in an anchor, and that anchor is pointing to a larger version of the image.

    Example

    Open type in a new window

    Code sample

    <image-lightbox alt="A large ball of twine">
  <a href="https://placehold.co/1000x500/eeeeee/111111/webp" aria-label="It’s complicated">
    <picture>
      <source srcset="https://placehold.co/600x300/eeeeee/111111/webp" media="(min-resolution: 3x)">
      <img width="200" height="100" src="https://placehold.co/400x200/eeeeee/111111/webp" alt>
    </picture>
  </a>
</image-lightbox>

    Notes

    • Use the custom element <image-lightbox> and wrap it around the anchor.
    • Add an alt attribute to the <image-lightbox> element to give the large image alternate text
    • Add an aria-label attribute to the anchor to give the thumbnail a title mask.
    • Make sure you only have one unique anchor per image URL - i.e. don't have more than one lightbox anchor on the same page pointing to the same image.