HTML image alt text: describe function or information, not pixels alone

Last updated: 1 Oct 20266 min read

tutorial

The alt attribute supplies text in place of an image when its visual content or function is unavailable.

Use it for a real task

The first icon acts as the only content of a link, so its alt names the destination. The second image is decorative beside an explicit text label, so an empty alt avoids repeating that label. A receipt chart needs the useful finding in alt and a nearby detailed account if the series matters.

<a href="/receipts/R-47">
  <img src="/media/receipt-open.svg" width="24" height="24"
       alt="Open receipt R-47">
</a>
<p><img src="/media/checkmark.svg" width="16" height="16" alt="">
   Approved receipt</p>

What the markup guarantees

The referenced assets are local application files and must exist. Avoid turning a complex chart into a one-sentence alt alone; give the data in adjacent prose or a table. If an image fails to load, meaningful alt should still tell the user what action or information it carried.

Cost and limits

Small icons are cheap to transfer, but shipping a large image at icon dimensions wastes bytes. Width and height reserve layout space; prepare an asset at a suitable intrinsic size.

Common Mistakes

Do not write 'image of' when the purpose is already clear.
Do not leave a linked icon without an accessible destination name.
An empty alt is correct only when the image adds no information or action.

Connected lessons

Related CSS decisions

CSS image-set: offer resolution choices for decoration

html

media