Everything I know about alt text

A good part of my job is telling peo­ple to use alt texts. To make my life eas­ier, here are all my notes and ref­er­ences in one place.
Apples on checked blanket with overlaid text: Apples on checked blanket

What is alt text?

Alt text” is short for alternative text”. It’s a short piece of text that’s used when the im­age it­self is­n’t avail­able be­cause some­one is us­ing a text-only or au­dio ver­sion of your web­site, they turned off im­ages to save band­width, or the net­work re­quest failed. Alt text also makes your im­ages more read­able for ma­chines, both your own and those built by oth­ers.

It’s dif­fer­ent to an im­age cap­tion, which pro­vides ad­di­tional con­text to an im­age and is vis­i­ble to every­one, or an ex­tended de­scrip­tion.

Why should you use alt text?

Alt text is a straight­for­ward way to give more peo­ple ac­cess to your con­tent. This in­cludes peo­ple who are blind or have low vi­sion and rely on screen read­ers and other as­sis­tive tech­nol­ogy, but also peo­ple who are cook­ing, dri­ving, on a slow in­ter­net con­nec­tion, or in some other sit­u­a­tion where an au­dio or text-only ver­sion of your web­site is just more con­ve­nient.

If your or­gan­i­sa­tion takes pub­lic money, you’re prob­a­bly re­quired to pro­vide alt text by your coun­try’s ac­ces­si­bil­ity laws. In the U.S. the rel­e­vant stan­dard is Section 508 of the Rehabilitation Act and the Americans with Disabilities Act (ADA)1, in Britain it’s the Public Sector Bodies (Websites and Mobile Applications) (No. 2) Accessibility Regulations 2018, and European mem­ber states all have lo­cal laws im­ple­ment­ing a di­rec­tive called EU 2016/2102. Thankfully, all of these laws re­fer to a com­mon stan­dard called the Web Content Accessibility Guidelines (WCAG), which re­quires that all non-text con­tent is also avail­able in text” (Success Criterion 1.1)

How do you write good alt text?


Alt text should give peo­ple the same in­for­ma­tion as the im­age it re­places. This means you need to ask what the pur­pose of the im­age is in the con­text it’s in and write dif­fer­ent alt text de­pend­ing on the an­swer.

Let’s say your web­site has a phone num­ber with an icon of a phone next to it. The pur­pose of that icon is just to in­di­cate that what fol­lows is, in fact, a phone num­ber — so the alt text should do the same. The word Phone” would be enough to do that. Any other de­tails would be dis­tract­ing.

If the point of an im­age is to show what some­thing looks like, the alt text should be a vi­sual de­scrip­tion of that thing, fo­cus­ing on the im­por­tant de­tails. If the im­age is a photo of a boat you’re try­ing to sell, you should fo­cus on the boat rather than the land­scape in the back­ground. However, if you used the same im­age as an ex­am­ple of your land­scape pho­tog­ra­phy, de­scrib­ing the back­ground, the light, and the over­all com­po­si­tion would make sense.

People have come up with more for­mal cat­e­gories of im­ages and rules for writ­ing alt texts for each. These can be use­ful, but ul­ti­mately these are ed­i­to­r­ial de­ci­sions you need to make us­ing your own judge­ment.


I think it’s help­ful to re­mind your­self that writ­ing alt text is still writ­ing. It’s not fun­da­men­tally dif­fer­ent from any other writ­ing you do on your web­site. This means you can use every­thing you know about your au­di­ence, struc­ture, tone, edit­ing and so on, and be as nu­anced and ex­pres­sive as you are in other con­texts. If you think of it as a lit­er­ary en­deav­our rather than a tech­ni­cal chore, writ­ing alt text can be fun and you’ll likely pro­duce bet­ter re­sults.

This be­ing said, some ba­sic style tips are gen­er­ally ac­cepted:

How do you add alt text?

It de­pends on your sit­u­a­tion. If you’re work­ing with HTML, you write the alt text right into your markup us­ing the alt at­tribute:

<img alt="Charcoal drawing of apples on checked blanket" src="apples.jpg" />

Inline SVGs don’t sup­port the alt-attribute, but you can use role="img" and aria-label in­stead:

<svg role="img" aria-label="Diagram of an internal combustion engine" viewBox=""></svg>

If you’re not edit­ing your site’s HTML di­rectly, you need to fig­ure out how to add alt text through your con­tent man­age­ment sys­tem. Most pop­u­lar ones have built-in tools to do it:

If your CMS does­n’t sup­port alt text, you can work around the prob­lem by adding cap­tions or de­scrib­ing the im­age in the main text.

Can you au­to­mate this?

Some peo­ple do gen­er­ate alt text au­to­mat­i­cally when no hand-writ­ten text is avail­able, no­tably Facebook and its prop­er­ties and Microsoft Edge.

The prob­lem with these sys­tems is that they have no way of know­ing what you were try­ing to com­mu­ni­cate with a par­tic­u­lar im­age. They just pro­duce a gen­eral, more or less ac­cu­rate de­scrip­tion of it, which is­n’t al­ways what your read­ers need (see above). Still, in most sit­u­a­tions it’s prob­a­bly bet­ter than no de­scrip­tion at all.

Further read­ing

  1. The U.S Department of Justice has some re­ally well-writ­ten guid­ance on how the ADA re­lates to web ac­ces­si­bilty. ↩︎