Learning objectives
Choose an image alternative by purpose; use dimensions to reserve space; resolve relative paths and inspect failed requests.
Prerequisites
Understand links, attributes, and the difference between a document-relative URL and an absolute URL.
Describe the image’s job
The img element embeds an image using a source URL. Its alternative text represents the image’s purpose when the image cannot be perceived. The right text depends on context. A photograph illustrating a walking route may need a short description of the terrain; the same photograph used as decoration next to a complete description may need an empty alt value.
For a functional image inside a link or button, the accessible name should explain the action or destination. A magnifying-glass picture that submits a search should mean Search, not Magnifying glass. Avoid repeating adjacent text unnecessarily. If a diagram communicates values or relationships that cannot fit in a short alternative, provide a concise identifier plus a nearby full explanation or data table.
Treat size and loading as part of the design
Width and height attributes describe the image’s intrinsic dimensions and allow the browser to calculate an aspect ratio before the file arrives. CSS can still make the rendered image responsive, for example max-width:100% and height:auto. Reserving space reduces unexpected movement as images load.
Use loading="lazy" for images that are safely below the initial viewport. Do not automatically lazy-load the page’s main visible image, because delaying it can delay the content a visitor came to see. The decoding attribute is a hint rather than a promise. Image formats, compression, dimensions, and the number of requests usually matter more than adding hints without measurement.
Use figure and figcaption when an image and its caption form a self-contained unit. A caption explains context visible to everyone; it does not automatically replace alt. For a chart, the caption may identify its source while the alternative explains what the image contributes.
Debug the URL, not just the tag
A relative source is resolved against the document’s base URL. Images/map.svg means an images folder relative to that location; /images/map.svg starts at the origin root. A file can work locally and fail after upload because the deployed path, letter case, or filename differs. Inspect the Network panel for the requested URL and response status. A 200 response containing an HTML error page is still not a valid image.
Working example
<figure>
<svg role="img" aria-labelledby="route-title" viewBox="0 0 320 100" width="320" height="100"><title id="route-title">A level path connecting the station to the library</title><path d="M20 70 L300 70" stroke="#147d64" stroke-width="8"/><circle cx="20" cy="70" r="10" fill="#1856cb"/><circle cx="300" cy="70" r="10" fill="#1856cb"/></svg>
<figcaption>The step-free route follows the canal.</figcaption>
</figure>Another example
<figure>
<img src="images/canal-path.jpg" alt="A wide paved path beside the canal" width="1200" height="800" loading="lazy">
<figcaption>The canal route is mostly level.</figcaption>
</figure>Expected output
The first example uses an inline vector so it works without a remote image request. It shows a simple route line with a caption. The second requires a real local image file at the declared path; the isolated editor deliberately blocks network image loading.
Common mistakes
Do not omit alt just because a filename is descriptive. Do not put essential text only inside a picture. Avoid width and height values that imply the wrong aspect ratio. Check whether your CMS rewrites filenames or moves uploads into dated directories.
Accessibility and browser notes
An empty alt identifies a decorative img for assistive technology; a missing alt has different behavior. Inline SVG uses its own accessible naming pattern, as shown in the first example. Test zoom, high contrast, and images disabled as separate situations.
Practice
A linked logo takes visitors to the homepage. Write markup with a useful name and dimensions. Explain why the brand name alone may not describe the destination.
Review the solution and reasoning
<a href="/"><img src="brand.svg" alt="North Library home" width="180" height="48"></a>The alternative becomes the link’s accessible name and includes its destination. If an equivalent visible text link were inside the same anchor, an empty alt could avoid repeating that text.