Media: images and alt text

Module 4: Creating content · Reading time: 9 minutes

Learning objective: After this lesson, you can prepare, upload and describe images properly, so they load fast, look sharp and are usable for everyone.

Key concepts: media library, image formats, big image threshold (2560 pixels), JPEG, PNG, WebP, AVIF, compression, srcset, lazy loading, alt text, file name, copyright

What happens when you upload a photo

You upload a photo from your phone: 4,000 by 3,000 pixels, 5 MB. WordPress then does more than you might think:

1. If the photo is wider or taller than 2,560 pixels, WordPress creates a scaled down version (with -scaled in the name) and uses that as the "original". The real original is also kept. This is called the big image threshold and has existed since WordPress 5.3.
2. WordPress also creates a series of smaller sizes: thumbnail (150 x 150 pixels by default, cropped), medium (300), large (1024), and extra sizes of 768, 1536 and 2048 pixels wide. Your theme and plugins often add their own sizes too.
3. All versions end up in wp-content/uploads/2026/11/ (year and month of the upload).

One photo can easily turn into eight or more files. That's why the uploads folder grows so quickly (lesson 1.3), and why it matters what you upload.

On the page, WordPress adds a srcset to an image: a list of all those sizes. The browser itself picks the smallest size that's sharp enough for the screen. A phone then loads the 768 pixel size, a large screen the 1536 one. That only works well if the sizes exist, so if you upload via the media library and not with FTP.

Resizing and compressing beforehand

Even with those automatic sizes, it pays to resize photos beforehand:

• Size: a photo that's never shown wider than 1,600 pixels on your website doesn't need to be 4,000 pixels wide. Resize it beforehand to around 2,000 pixels on the long side. That saves storage, backup size and upload time.
• Compression: a JPEG with quality 75 to 85 looks almost the same to the eye as quality 100, but is often half the size.
• Metadata: photos from a phone often contain the GPS location where they were taken. If you don't want everyone to know where you live, remove that before uploading. WordPress strips a lot of metadata from the smaller sizes, but the original may still contain it.

There are plugins that compress images on upload or convert them to a more modern format. Handy, but check whether they do this on your own server or send the photos to an external service (lesson 9.3), and whether you really need a plugin if you can also do it beforehand.

Which format

If your server can't process a format, WordPress either shows an error when uploading or doesn't create smaller sizes. In Tools > Site Health (Info tab, under Media Handling) you can see which formats your server supports.

Lazy loading

Since WordPress 5.5, images automatically get loading="lazy": the browser only loads an image once you scroll to it. That makes a long page with lots of photos much faster. WordPress deliberately leaves the first large image at the top of the page without lazy loading and often gives it priority with fetchpriority="high", because it needs to be visible as quickly as possible. You'll come back to this in lesson 6.3.

Always set width and height on an image too (WordPress does this for images from the media library). That way the browser reserves space in advance and the text doesn't jump around when the photo comes in.

Alt text: for those who can't see the image

The alt text (alternative text) describes what's shown in an image. Screen readers read it aloud to blind and visually impaired visitors, and it appears if the image doesn't load. Search engines use it to understand the image.

A good alt text describes what the image says in this context:

• Poor: IMG_4032.jpg or photo.
• Poor: bike shop bike e-bike buy cheap bike (stacking keywords helps no one).
• Good: Mechanic adjusting the brakes of a blue e-bike in the workshop.

If an image is purely decorative (a line, a background pattern), leave the alt text empty. Then a screen reader skips it. Empty is different from missing: an image without alt often has its file name read out by a screen reader. An image that's a link (for example a logo that links to the homepage) describes where the link goes: To the homepage of Fietsenwinkel De Spaak.

In the media library, you add the alt text to the image itself, and in the block editor to the image block. Note: an alt text you fill in in the media library doesn't automatically change on images already placed on pages.

File names and copyright

• File name: e-bike-remmen-afstellen.jpg says more than IMG_4032.jpg and appears in the image's address. Lowercase letters, hyphens, no spaces.
• Copyright: an image from Google Images isn't free to use. Photographers and stock photo agencies regularly send invoices for use without a licence. Use your own photos, photos with a clear licence, or a stock photo agency whose terms you know, and keep proof of your licence.

Storage and tidying up

The media library doesn't tidy itself up. An image you remove from a page stays in the library and in uploads, with all its sizes. On a website with years of content, that adds up. Tidy up occasionally, but carefully: an image might be used somewhere the library doesn't see (in a theme setting, a widget or an email). Make a backup first.

Summary

• WordPress creates multiple sizes from every upload and resizes large photos to 2,560 pixels; the browser picks the right size via srcset.
• Resize and compress photos beforehand and remove location data.
• Use JPEG or WebP for photos, PNG for logos and screenshots; SVG only with a plugin that cleans it up.
• Lazy loading happens automatically, except for the first large image; width and height prevent content jumping around.
• Alt text describes what the image says in context; purely decorative images get empty alt text.

Quiz

Exercise

Exercise A4.4: Images on your homepage. Enter your website's address. The tool reads the homepage and checks the first 20 images: do they have an alt attribute (empty is fine, missing isn't), do they have width and height, and how large is each file (via a HEAD request)? Images over 300 kB are flagged. Fix whatever's flagged in your media library or on the page, and check again.

Further reading

These articles describe the steps in WebOké's control panels; they work similarly in other panels.

• DirectAdmin guide 18.5: Upload too large (error 413) or timeout
• Upload fails: increase upload_max_filesize and max_execution_time
• Media Library Screen (wordpress.org, English): https://wordpress.org/documentation/article/media-library-screen/
• Writing alt text (W3C, English): https://www.w3.org/WAI/tutorials/images/decision-tree/