Image Guidelines

In general, we want to have the best visual experience for the least amount of load time and document size. There are a few guidelines outlined below to help facilitate this.

Images on the website

Here is several different things that should be in place when you're done coding your html website, depending on whether it is a background image, or an image tag

Image

An image on a website should look like this:

Image File

The first part is the src or image source. This is the file you upload to the file server. The file should be an SVG or webP image, sized to the maximum width/height it will appear on the website, compressed. A deeper dive on this can be found below.

Lazy Loading

Every img tag should have a loading property on it. The value in that should be either "lazy" or "eager". Only eager if it is above the fold (usually the logo and img in the hero section are the only ones that get this). Lazy for everything else (when in doubt, stick with lazy).

Aspect Ratio

Every image tag should have an aspect-ratio CSS property on it. It can be in the style for that image, and is not necessary if an image has a height and a width on it. The easiest thing to do is to put it in an inline style on the tag like the example above. The value for the aspect ratio should be "auto" followed by a space and whatever the rendered aspect-ratio for an image is. You can find where to find that below.

Width or Height

In order for the aspect-ratio to work, you need a width or height attached to it. Technically it will work with a width or height in the styles for that image. But in order to keep scanners satisfied, it's recommended to put a "width" or "height" property on the image with the pixel size for one of those values of essentially what the max-width/height for the image is. Further elaboration below.

Alt text

It's not our job to put the text in there, but you should make sure the value of alt is in there.

Background Image

A background-image should go on a page (generally) should look like this:

There are several exceptions, however.

Background Image File

Like the regular images on a webpage, you should size the source file down to the biggest the background will be. However, considering 4k monitors, file sizes can get big. They should also be compressed. More details below.

Lazy loading

This gets a little tricky these days. Dave Webb built a lazyload feature for backgrounds into PagePilot, but it can't be applied to backgrounds in media queries, on ::before or ::after pseudo-elements, or backgrounds with multiple images. In general, you should set up a background image like the example above though. Further details below.

Important note: When doing the background image lazyload, make sure you don't have any inline styles on the object, or they will be overridden (elaboration below).

---

Image Files

Before even uploading the final version of an image to the file server, there are a few things we can do to make the most efficient file.

1. Correct file format

We mostly use Webp images for the website. But sometimes SVGs are better, and very rarely, a different file format might be smaller than WebP.

Webp is a raster graphics file format that generally is less file size than jpg, but supports transparency, lossless, and lossy compression. Only in the past few years has WebP file format been accepted by all major browsers.

You can either convert your files online, but photoshop does let you save files (with no additional layers) as a WebP format. Simply save an image as a Webp, and for our purposes, you'll want to save it lossy, the quality depends on your use case, above the fold you want to keep it a higher quality, but can go high or even medium lower down.

Make sure you compress it online as well. Photoshop can do a decent job, but sites like TinyPng are good additional measures.

WebP file comparison

If you look at the difference in file size on your computer's browser, the difference can be obvious.

2. Size the image to not be bigger than its largest use case.

Image files should be no larger than the largest use case on the website. Kind of think of it as its max-width. You can check by putting in the placeholder for an image, and inspect it. Resize your screen to be full width down to medium and see where the image is at its largest. Sometimes this is on md screen sizes because of the breakpoint, so make sure you check.

In the above example, the image on the left is desktop size, the image is 540px width, but the right side is tablet view, where the image is 690px wide. In this example, you would want to size your image file at 690px wide.

When it comes to background images, (specifically for files) we don't need the image to be bigger than the width of a 1080p monitor, which is 1920px wide. That means if you have a background image on say a col-6 of a container-fluid, it only needs to be 960px wide (half of 1920px).

Lazy Loading

On img tags, for once this is really simple, just add 'loading="lazy"' to the image tag, or set it to eager if it's above the fold.

Backgrounds, this is a different conditional setting.

Background image lazyload

When you can lazyload a background image, you should. Obviously don't do this on the hero image, but in other places, add the class "lazyload" to the element (anything with a background element, doesn't have to be sections). Then add the property on that element "data-src" with the value being the url for the image file. Example: 'data-src="/wahelper/GetImage?id=123456"'.

What this does is there's a script on our websites that take the url out of the "data-src" and insert it as inline-style on that element when it comes into view on the page. This means you need to make sure your background styles on the element can't use the "background" shorthand CSS property.

Exceptions

This doesn't work in 3 major cases:

1. Background images in a media query
2. Pseudo elements
3. Multiple background images

1. Media Query

Since the background lazy load puts the background as an inline style, you can't set it to change at different screen sizes, so you can't use it if you have different images at different screensizes:

2. Pseudo-Elements

This isn't very common, but sometimes in order to place a background image you move around, it'll be set up with a ::before or ::after pseudo-element. In these cases those elements aren't available in the html to put a class of "lazyload" on.

3. Multiple background images

Some elements you layer background images on. This could be a gradient over an image, or stacking images, whatever the reason. Because the script wraps the data-src in a "url()", you can't have multiple images or gradients in there.

Important note on background lazyload

Because the lazyload adds an inline style to the element, if you have any inline style on the element already, they will be overridden with the background image, so be mindful.

Aspect-Ratio

This is a new CSS property that we can use (on the image tag) to eliminate CLS (cumulative layout shift). Essentially how a webpage works is it puts an empty spot where the image is supposed to be when creating the webpage based on the html. When the image finally loads, it goes into that empty spot, and can push content around. To avoid this, we use the "aspect-ratio" property to have it reserve space on the website.

To set it up you need to have a width or a height declared on the image (recommended using the width or height property). Then in your styles, or as inline on the element add the property "aspect-ratio", and give it a value of "auto", a space, and then the aspect ratio of the image. Example: 'aspect-ratio: auto 12/23;'.

The aspect ratio value is a fraction, so you don't have to worry about it being minimized (you don't have to change 50/50 to 1/1), because the system does the math for you. The "auto" part of the value is also a failsafe, basically it will revert to the image's proper aspect-ratio once the image loads.

How to get an image's aspect-ratio

There are two ways to get the aspect ratio. One, just put its height and width as a fraction [height]/[width] (690/389.19).

Or, just copy the 'Rendered aspect ratio:' value from the inspect element in your browser, when you hover over the source of an image. Just make sure to replace the ":" with a "/". (You can literally highlight that value and paste it in the CSS property's value, and replace the ":").

Width or Height

So, PagePilot has built into our websites the CSS of 'max-width: 100%;' on all img tags. This means that (as long as you don't put a max-width on an image) if you put a width on an image, it will shrink to fit its container still. This is why we put a hard-set width on images, but not on other elements.

Of course you can put a height instead, and that should work just fine.

This can be rendered as a width CSS property on the element (width: 500px;), but for scanners and auditors to see on the website, we prefer the use of the "width" or "height" property on img tags.

These are written out as 'width="500"' or 'height="500"'. Specifically the value you put in is expected to be a pixel measurement, and not have the 'px' unit on the end. The only exception is you can put "100%" as a value instead.