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 quickly, look sharp and work for everyone.

Key concepts: Media Library, image sizes, big image threshold (2,560 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 kept as well. This is called the big image threshold and has existed since WordPress 5.3.
2. WordPress also creates a set 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 go into wp-content/uploads/2026/11/ (the year and month of the upload).

So one photo quickly becomes eight or more files. That is why the uploads folder grows so fast (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 is sharp enough for the screen. A phone then loads the 768-pixel size, a large screen the 1536 one. This only works well if the sizes exist, so if you upload through the Media Library and not via FTP.

Resize and compress beforehand

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

• Dimensions: a photo that is never shown wider than 1,600 pixels on your website does not need to be 4,000 pixels wide. Resize it beforehand to about 2,000 pixels on the long side. That saves storage, backup size and upload time.
• Compression: a JPEG at 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 it 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 cannot process a format, WordPress shows an error on upload or does not create the smaller sizes. In Tools > Site Health, on the 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 when you scroll towards it. That makes a long Page with many 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 a width and height on an image too (WordPress does this for images from the Media Library). The browser then reserves space in advance and the text does not jump when the photo comes in.

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

The alt text (alternative text) describes what is in an image. Screen readers read it aloud to blind and visually impaired visitors, and it appears when the image does not load. Search engines use it to understand the image.

Good alt text describes what the image says in this context:

• Bad: IMG_4032.jpg or photo.
• Bad: bike shop bike e-bike buy cheap bike (stuffing 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. A screen reader then skips it. Empty is not the same as missing: with an image without alt, a screen reader often reads out the file name. An image that is a link (for example a logo that goes to the homepage) describes where the link goes: Go to the homepage of De Spaak bike shop.

In the Media Library you set the alt text on the image itself, and in the block editor on the Image block. Caution: alt text you enter in the Media Library does not automatically change for images that are already on Pages.

File names and copyright

• File name: e-bike-remmen-afstellen.jpg says more than IMG_4032.jpg and ends up in the image's address. Use lower case, hyphens and no spaces.
• Copyright: an image from Google Images is not free to use. Photographers and stock libraries regularly send invoices for use without a licence. Use your own photos, photos with a clear licence or a stock library whose terms you know, and keep proof of your licence.

Storage and tidying up

The Media Library does not 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 now and then, but carefully: an image may be used somewhere the library can't see (in a theme setting, a widget or an email). Make a backup first.

Summary

• WordPress creates several sizes from every upload and scales large photos down 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 sanitises it.
• Lazy loading is automatic, except for the first large image; width and height prevent content from jumping.
• 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 program reads the homepage and looks at the first 20 images: do they have an alt attribute (empty is fine, missing is not), do they have a width and height, and how large is each file (via a HEAD request)? Images over 300 kB are reported. Fix whatever is red in your Media Library or on the Page, and check again.

Further reading

These articles describe the steps in WebOké's control panels; other panels work in a similar way.

• DirectAdmin guide 18.5: Upload too large (error 413) or timeout
• Upload fails: increase upload_max_filesize and max_execution_time
• Media Library (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/