Skip to main content

Alt Text for Images: How to Write Good Alt Text

Information about the article

Portrait of Dmitry Dugarev

Author: Dmitry Dugarev

Consultant for digital accessibility & IT compliance

Last updated on:

Good alt text for images replaces the image for everyone who cannot see it. This guide is for editors, website owners and developers. You will learn how to write alt text that makes an image accessible, and which alt text suits each type of image. Every type comes with an HTML example, plus the settings you need in WordPress.

In short
  • Every image needs an alt attribute. The purpose of the image decides what goes in it [1].
  • Decorative images get an empty alt="". Screen readers then ignore them [2].
  • If an image is the only content of a link or button, the alt text names the destination or the action [3].
  • In WordPress, alt text in the Image block applies only to that post. The featured image, by default, takes its alt text from the Media Library [4], [5].

What is alt text (alternative text)?​

Alt text is the value of the alt attribute on an <img> element. Its full name is alternative text. In this article, I use the short form: alt text.

Alt text is the text version of the image. The HTML standard offers a simple test: replace every image with its alt text. The meaning of the page must stay the same [6].

These people and programs use alt text:

  • Screen readers: They read the alt text aloud. Blind users learn what the image shows or does [7].
  • Braille displays: They output the alt text in braille [7].
  • Voice control: Users say the alt text of an image link or button. One spoken command moves the focus there [7].
  • Slow connections: People who turn off images or have a poor connection see the text instead [6], [8].
  • Search engines: Google uses alt text to understand what an image shows [8].

Alt text is not a caption. According to the HTML standard, a title, legend or caption never belongs in the alt attribute [6]. The caption is visible to everyone in the <figcaption>. The alt text replaces the image.

What WCAG and the BFSG require for alt text​

The rule comes from WCAG 2.2, success criterion 1.1.1 "Non-text Content" (Level A). All non-text content that the page presents to the user needs a text alternative that serves the same purpose [1]. The criterion lists a few exceptions. For images, the most important one is pure decoration. You implement such images so that assistive technology can ignore them [1].

In Germany, the legal basis is the BFSG (Barrierefreiheitsstärkungsgesetz, Germany's implementation of the European Accessibility Act, EAA). Under § 4 BFSG, a presumption of conformity applies to harmonized standards whose references are published in the Official Journal of the EU [9]. So far, no harmonized standard for the BFSG has been published there [10]. For websites, EN 301 549 is the technical benchmark. Its new version V4.1.1 from September 2026 is the first one written for the EAA. It follows WCAG 2.2 [11], [12].

This version creates a presumption of conformity only once the EU cites it in the Official Journal [11]. Until then, according to AccessibleEU, version V3.2.1 remains the usual reference [12]. Both versions adopt criterion 1.1.1 for web pages in clause 9.1.1.1 [11], [13]. For the legal background, see the overview of the BFSG and the EAA.

A second criterion covers text in images. Under WCAG 1.4.5, Level AA, you use real text instead of images of text whenever the technology allows it [14]. There are two exceptions. Either users can adjust the image of text themselves, or the presentation is essential. Logos count as essential [14].

Alt text for images: five image types​

The W3C groups images by their purpose [7]. Whether an image looks nice does not matter. The question is: what would users miss if the image were gone?

Informative images​

An informative image shows information that is not in the text. The alt text gives this information in one short sentence [15]. Describe what matters for this page.

<!-- Product photo in a shop: the user needs the color and material -->
<img src="oak-chair.jpg" alt="Dining chair in light oak with a gray fabric seat" />

Decorative images with alt=""​

An image is decorative if it is only there for decoration. An image is also decorative when the text next to it already gives the same information [16]. These images get an empty alt="" [2].

Never drop the attribute entirely. Without it, some screen readers read out the file name [16]. Do not put a space between the quotation marks either [17]. A decorative image also has no title attribute [2]. Images that are part of the page design are best added with CSS [6], [18].

<!-- Decorative graphic next to a heading -->
<img src="wave.svg" alt="" />

Not sure whether your image is decorative? The decision tree for alt text below answers that in four questions.

An image is functional if it is the only content of a link or button. Then the alt text describes the action or the destination [3], [6]. A magnifying glass icon in a search button gets the alt text "Search", not "Magnifying glass". The logo in the header often links to the home page. So its alt text names the company and the destination [3].

<!-- Logo as a link to the home page -->
<a href="/"><img src="logo.svg" alt="Example Ltd, home page" /></a>

<!-- Icon button without visible text -->
<button type="submit"><img src="magnifier.svg" alt="Search" /></button>

Here the alt text becomes the accessible name of the link. If the link already contains text next to the image that describes its purpose, the image can have alt="" [19].

Images of text​

If an image shows only text, the alt text contains exactly that text [6], [20]. Do not describe the font or the shadow. That satisfies criterion 1.1.1.

A promotional banner built as an image still fails WCAG 1.4.5 (Level AA). The reason: CSS can display the same text [14]. So build such banners with real text. Real text stays sharp when zoomed, and users can change its colors [20]. Logos are exempt from this rule [14].

If the text stays in the image, it needs enough contrast against the background. Criterion 1.4.3 also applies to images of text [21]. Check the contrast ratio with our WCAG 2.2 contrast checker.

<!-- Meets 1.1.1, but fails 1.4.5 -->
<img src="sale-banner.png" alt="Summer sale: 20% off all garden furniture until August 31" />

<!-- Better: real text, styled with CSS -->
<p class="sale-banner">Summer sale: 20% off all garden furniture until August 31</p>

Complex images: charts and diagrams​

Charts, org charts and maps contain too much for one sentence. They need two parts [22]. The alt text says briefly what the image is. A long description provides the data [23].

The long description can sit directly below the image or on a separate page [24], [25]. You can also link it to the image with aria-describedby [22].

<figure>
<img
src="revenue-2026.png"
alt="Bar chart: revenue per quarter in 2026. Details in the table below."
/>
<table>
<!-- The numbers from the chart as a real table -->
</table>
<!-- figcaption is the first or last child of figure -->
<figcaption>Revenue per quarter in 2026, in thousands of euros</figcaption>
</figure>

When several images convey one piece of information, one image gets the alt text for the whole group [26]. A five-star rating is a typical example. The first star gets an alt text such as "3.5 out of 5 stars". The other stars get alt="" [26].

Decision tree for alt text​

The W3C offers a decision tree for the alt attribute [27]. I have cut it down to four questions for everyday use.

Show the text description of "Decision tree: which alt text fits my image?"

The decision tree uses four questions to find the right alt text.

  1. Is the image the only content of a link or button?
    • Yes: The alt text names the destination or the action.
    • No: go to question 2.
  2. Does the image contain text that is not already in the nearby text?
    • Yes: The alt text repeats exactly that text.
    • No: go to question 3.
  3. Would users miss information without the image?
    • No: The image gets an empty alt attribute.
    • Yes: go to question 4.
  4. Does the information fit in one short sentence?
    • Yes: A short alt text is enough.
    • No: The image gets a short alt text and a long description.

How to write alt text: six rules​

The image types tell you whether an image needs alt text. These rules help you phrase it.

  1. Context decides. The same photo may need different alt text on two different pages [7]. On the team page, the person's name matters. In a blog post about office design, the room matters.
  2. Keep it as short as possible. Good alt text is the most concise description of the image's purpose [17]. The German Federal Accessibility Agency (Bundesfachstelle Barrierefreiheit) puts it this way (my translation): "as detailed as necessary, as brief as possible" [28]. WCAG 1.1.1 sets no fixed character limit [1]. If you need more than one sentence, use a long description [17].
  3. No "image of". Words like "image", "photo" or "icon" are usually unnecessary [17]. In my tests, screen readers already announce the role "image" or "graphic" on their own.
  4. No file names or placeholders. alt="IMG_4711.jpg" or alt="image" is not an alternative. WCAG explicitly lists this as a failure [29].
  5. No keyword stuffing. A list of search terms helps no user. Google may treat such a page as spam [8].
  6. Use punctuation. Periods and commas help when the text is read aloud [17]. If the image sits directly next to text, remember to add a space in the alt text [17].

The title attribute does not replace alt text. Many devices and browsers do not show the title at all [4].

How to add alt text in WordPress​

WordPress has two places for alt text: the Media Library and the Image block in the editor. According to the WordPress documentation, alt text in the block applies only to the image in this post [4]. The alt text in the Media Library is only the default value each time you insert the image [4].

This comes down to the code. The Image block stores the alt text directly in the post's <img> tag [30]. If you later change the alt text in the Media Library, the Image block keeps the old one. This mostly affects older posts. I see it often in my audits: the Media Library is well maintained, but the image in the post still has an empty alt.

The featured image works differently. WordPress outputs it with the function wp_get_attachment_image() [31]. This function reads the alt text from the Media Library on every page load [5]. Themes and plugins can use the same function. For these images, edit the alt text in the Media Library.

Here is how to set alt text in the block editor:

Select the Image block​

Click the image in the editor. Open the block settings on the right. If the sidebar is hidden, click the settings icon in the top bar [4].

Enter the alternative text​

The field for the alternative text is in the Content tab of the block settings [4]. Write it for this specific post. The link next to the field, "Describe the purpose of the image", opens the W3C decision tree [4].

Mark decorative images​

If the image is only decoration, use the "Mark as decorative" option in the Content tab [4]. According to the roadmap, this option is part of WordPress 7.1 [32]. It clears the alt text field, hides the caption and sets role="none" on the image [33].

Be careful: any existing alt text and the caption are lost without warning. Unchecking the option does not bring them back [34]. If your WordPress version does not have this option, leave the alt text field empty. For decorative images, also leave the title attribute in the Advanced settings empty [2], [4].

Check the front end​

Open the page and check the alt attribute in the source code. My audits show that some themes and plugins change the output. What counts is the result in the browser.

If you use a page builder, every image widget has its own rules. For details, see the guides for Elementor and Divi. The article on WordPress accessibility gives an overview.

AI-generated alt text: useful, with limits​

Modern AI models describe images at the click of a button [35]. This saves time with large media libraries. But the AI usually sees only the image, not your page.

The purpose of an image depends on its context [7]. A study presented at the ASSETS 2024 conference looked at this. In 2024, common tools described images without considering the context of the web page [35]. The 12 blind and low-vision participants rated context-aware descriptions much higher [35].

The American Foundation for the Blind points to a second risk. AI models sometimes invent details that are not in the image at all [36]. Blind users have no way to check them.

So use AI only for a first draft. Check every suggestion with these questions:

  • Is the image decorative? Then delete the suggestion and set alt="".
  • Is the image the only content of a link or button? Then the alt text names the destination, not the subject.
  • Is every detail correct? Check product names, colors and numbers yourself.
  • Does the text fit this post? The AI does not know your page.

Alt text and SEO​

Google calls alt text the most important attribute for providing metadata about an image [8]. Google uses it together with computer vision and the content of the page [8]. If an image is a link, its alt text serves as the anchor text [8].

Google recommends useful descriptions that fit the context of the page, that use keywords appropriately [8]. Accessibility follows the same rule. So good alt text for screen readers is also good alt text for Google.

There is one difference: the file name. Google recommends short, descriptive file names [8]. So name the file oak-dining-chair.jpg instead of IMG00023.jpg. But the file name never belongs in the alt attribute [29].

Check the alt text on your website​

Missing alt text is very common. The WebAIM Million 2026 study analyzed one million home pages. 53.1% of them had at least one image without alt text [37]. Overall, 16.2% of all images had no alt text [37].

Another 10.8% of the images with alt text had questionable or repetitive alt text [37]. Examples include "image", a file name, or a repeat of the text right next to the image [37].

A tool can find missing alt attributes. Our free BFSG check checks this on one page of your website, for example the home page. Whether the alt text fits the purpose of the image can only be checked manually. The tool does not know the context of the page and cannot see whether an image is decorative.

I do this manual check in my audit according to WCAG 2.2. If alt text is missing in many posts, I can also take care of the remediation in your existing WordPress site. The sample audit report shows what a finding on criterion 1.1.1 looks like. Overlay tools do not solve the problem. I explain why in the article on overlays and the BFSG.

Frequently asked questions (FAQ)​

Does every image need alt text?​

Every image needs an alt attribute. Informative and functional images get a text alternative [1]. Decorative images get an empty alt="", so the screen reader skips them [2]. If the attribute is missing and there is no aria-label, aria-labelledby or title either, that is a failure under WCAG [38]. Still, always set alt. It is the safest option.

How long should alt text be?​

WCAG sets no fixed limit [1]. The W3C recommends the most concise description of the purpose [17]. One short sentence is usually enough. If you need more, put the rest in a long description next to the image [22].

What is the difference between alt text and a caption?​

All users see the caption below the image. The alt text replaces the image when it is not visible. According to the HTML standard, the caption never belongs in the alt attribute [6].

Where do I add alt text in WordPress?​

In the block editor, select the image and open the block settings. The field for the alternative text is in the Content tab [4]. In the Image block, the text from the Media Library only pre-fills the field when you insert the image [4]. Featured images, however, take their alt text directly from the Media Library by default [5], [31].

Can I use AI to write alt text?​

Yes, as a draft. But the AI does not know the context of your page [35]. It can also invent details [36]. So check every suggestion yourself before you publish it.


Disclaimer​

The content of this article has been researched to the best of my knowledge and is for general information only. It does not constitute legal advice and cannot replace individual advice from a lawyer who considers your specific situation.

No guarantee is given for the accuracy, completeness or timeliness of the information. Any action you take based on the information provided here is at your own risk.

​

  1. W3C, “Success Criterion 1.1.1 Non-text Content,” 2023, [Online]. Available: https://www.w3.org/TR/WCAG22/#non-text-content ⤴
  2. W3C, “H67: Using null alt text and no title attribute on img elements for images that assistive technology should ignore,” 2023, [Online]. Available: https://www.w3.org/WAI/WCAG22/Techniques/html/H67 ⤴
  3. W3C Web Accessibility Initiative (WAI), “Functional Images.” 2017. [Online]. Available: https://www.w3.org/WAI/tutorials/images/functional/ ⤴
  4. WordPress.org, “Image block.” 2026. [Online]. Available: https://wordpress.org/documentation/article/image-block/ ⤴
  5. WordPress.org, “wp_get_attachment_image() - Function.” 2026. [Online]. Available: https://developer.wordpress.org/reference/functions/wp_get_attachment_image/ ⤴
  6. WHATWG, “HTML Living Standard, 4.8.4.4 Requirements for providing text to act as an alternative for images.” 2026. [Online]. Available: https://html.spec.whatwg.org/multipage/images.html#alt ⤴
  7. W3C Web Accessibility Initiative (WAI), “Images Tutorial.” 2026. [Online]. Available: https://www.w3.org/WAI/tutorials/images/ ⤴
  8. Google Search Central, “Image SEO best practices.” 2026. [Online]. Available: https://developers.google.com/search/docs/appearance/google-images ⤴
  9. Bundesministerium der Justiz und für Verbraucherschutz, “Gesetz zur Umsetzung der Richtlinie (EU) 2019/882 des Europäischen Parlaments und des Rates über die Barrierefreiheitsanforderungen für Produkte und Dienstleistungen (Barrierefreiheitsstärkungsgesetz – BFSG).” 2023. [Online]. Available: https://www.gesetze-im-internet.de/bfsg/ ⤴
  10. Bundesfachstelle Barrierefreiheit, “Normen und Standards zum BFSG.” 2026. [Online]. Available: https://www.bundesfachstelle-barrierefreiheit.de/DE/Barrierefreiheitsstaerkungsgesetz/Normen-und-Standards/normen-und-standards_node ⤴
  11. ETSI, CEN und CENELEC, “EN 301 549 V4.1.1 (2026-09) - Accessibility requirements for ICT products and services.” 2026. [Online]. Available: https://www.etsi.org/deliver/etsi_en/301500_301599/301549/04.01.01_60/en_301549v040101p.pdf ⤴
  12. AccessibleEU, “The European accessibility standard EN 301 549 has been updated.” 2026. [Online]. Available: https://accessible-eu-centre.ec.europa.eu/content-corner/news/european-accessibility-standard-en-301-549-has-been-updated-2026-09-07_en ⤴
  13. ETSI, “ETSI EN 301 549 V3.2.1 (2021-03) - Accessibility requirements for ICT products and services.” 2021. [Online]. Available: https://www.etsi.org/deliver/etsi_en/301500_301599/301549/03.02.01_60/en_301549v030201p.pdf ⤴
  14. W3C, “Success Criterion 1.4.5 Images of Text,” 2023, [Online]. Available: https://www.w3.org/TR/WCAG22/#images-of-text ⤴
  15. W3C Web Accessibility Initiative (WAI), “Informative Images.” 2019. [Online]. Available: https://www.w3.org/WAI/tutorials/images/informative/ ⤴
  16. W3C Web Accessibility Initiative (WAI), “Decorative Images.” 2019. [Online]. Available: https://www.w3.org/WAI/tutorials/images/decorative/ ⤴
  17. W3C Web Accessibility Initiative (WAI), “Tips and Tricks (Images Tutorial).” 2024. [Online]. Available: https://www.w3.org/WAI/tutorials/images/tips/ ⤴
  18. W3C, “C9: Using CSS to include decorative images,” 2023, [Online]. Available: https://www.w3.org/WAI/WCAG22/Techniques/css/C9 ⤴
  19. W3C, “H30: Providing link text that describes the purpose of a link for anchor elements,” 2023, [Online]. Available: https://www.w3.org/WAI/WCAG22/Techniques/html/H30 ⤴
  20. W3C Web Accessibility Initiative (WAI), “Images of Text.” 2017. [Online]. Available: https://www.w3.org/WAI/tutorials/images/textual/ ⤴
  21. W3C, “Success Criterion 1.4.3 Contrast (Minimum),” 2023, [Online]. Available: https://www.w3.org/TR/WCAG22/#contrast-minimum ⤴
  22. W3C Web Accessibility Initiative (WAI), “Complex Images.” 2026. [Online]. Available: https://www.w3.org/WAI/tutorials/images/complex/ ⤴
  23. W3C, “G92: Providing long description for non-text content that serves the same purpose and presents the same information,” 2023, [Online]. Available: https://www.w3.org/WAI/WCAG22/Techniques/general/G92 ⤴
  24. W3C, “G74: Providing a long description in text near the non-text content, with a reference to the location of the long description in the short description,” 2023, [Online]. Available: https://www.w3.org/WAI/WCAG22/Techniques/general/G74 ⤴
  25. W3C, “G73: Providing a long description in another location with a link to it that is immediately adjacent to the non-text content,” 2023, [Online]. Available: https://www.w3.org/WAI/WCAG22/Techniques/general/G73 ⤴
  26. W3C Web Accessibility Initiative (WAI), “Groups of Images.” 2022. [Online]. Available: https://www.w3.org/WAI/tutorials/images/groups/ ⤴
  27. W3C Web Accessibility Initiative (WAI), “An alt Decision Tree.” 2024. [Online]. Available: https://www.w3.org/WAI/tutorials/images/decision-tree/ ⤴
  28. Bundesfachstelle Barrierefreiheit, “Alternativtexte.” 2026. [Online]. Available: https://www.bundesfachstelle-barrierefreiheit.de/DE/Fachwissen/Informationstechnik/Barrierefreie-Social-Media/Alternativtexte ⤴
  29. W3C, “F30: Failure of Success Criterion 1.1.1 and 1.2.1 due to using text alternatives that are not alternatives (e.g., filenames or placeholder text),” 2023, [Online]. Available: https://www.w3.org/WAI/WCAG22/Techniques/failures/F30 ⤴
  30. WordPress Gutenberg, “block.json des Bild-Blocks (core/image).” 2026. [Online]. Available: https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image/block.json ⤴
  31. WordPress.org, “get_the_post_thumbnail() - Function.” 2026. [Online]. Available: https://developer.wordpress.org/reference/functions/get_the_post_thumbnail/ ⤴
  32. Make WordPress Core, “Roadmap to 7.1.” 2026. [Online]. Available: https://make.wordpress.org/core/2026/06/19/roadmap-to-7-1/ ⤴
  33. WordPress Gutenberg, “Image block: Add ‘Mark as decorative’ toggle for accessibility (Pull Request 78064).” 2026. [Online]. Available: https://github.com/WordPress/gutenberg/pull/78064 ⤴
  34. WordPress Gutenberg, “Checking the ‘Mark as decorative’ checkbox discards existing alternative text and caption (Issue 82002).” 2026. [Online]. Available: https://github.com/WordPress/gutenberg/issues/82002 ⤴
  35. A. G. Mohanbabu and A. Pavel, “Context-Aware Image Descriptions for Web Accessibility.” 2024. [Online]. Available: https://doi.org/10.1145/3663548.3675658 ⤴
  36. A. Katsarakes, “Beyond Alt Text: Rethinking Visual Description in the Age of AI.” 2025. [Online]. Available: https://afb.org/blog/entry/alt-text-age-ai ⤴
  37. WebAIM, “The WebAIM Million: The 2026 report on the accessibility of the top 1,000,000 home pages.” 2026. [Online]. Available: https://webaim.org/projects/million/ ⤴
  38. W3C, “F65: Failure of Success Criterion 1.1.1 due to omitting the alt attribute or text alternative on img elements, area elements, and input elements of type ‘image,’” 2023, [Online]. Available: https://www.w3.org/WAI/WCAG22/Techniques/failures/F65 ⤴

About the author

Portrait of Dmitry Dugarev

Best regards,

Dmitry Dugarev

Founder of Barrierenlos℠. I test websites by hand and fix the barriers on WordPress websites – without a relaunch.