How to Write Alt Text for Images in WordPress
Write WordPress alt text that communicates an image’s purpose, handles decorative and linked images correctly, and is easy to add in the editor.
To write alt text in WordPress, describe the information or function an image adds to its particular page. If the image is decorative, mark it as decorative or use empty alternative text so assistive technology can skip it. For a linked image, describe where the link goes or what it does. Keep the wording concise, accurate, and free of unnecessary keywords.
A useful test is: if someone could not see the image, would this text preserve the meaning or action they need? WordPress describes the goal as replacing each image with its alternative text without changing the meaning of the page. WordPress documentation on media explains that principle.
1. Decide what the image is doing
Do not begin by listing every visible object. First consider the image’s role in context. The same photo might be informative in one article, decorative in another, or serve as a link in a third. Choose the text based on what the image contributes there.
| Image purpose | What to enter | Example |
|---|---|---|
| Informative | Describe the useful information the image adds. | Bar chart showing support requests rising from January through March |
| Decorative | Use empty alternative text, or select “Mark as decorative” in the Image block. | alt="" |
| Image containing meaningful text | Include the text if it is not available nearby in normal page text. | Banner announcing the store closes at 6 p.m. on Friday |
| Linked image | Describe the link’s destination or purpose. | View the 2026 accessibility checklist |
| Complex image | Give a short identification and explain its important details in nearby text. | Diagram of the three stages in the approval process, followed by a full text explanation |
WordPress’s accessibility guidance recommends concise descriptions for informative images, empty alt text for decorative images, and a fuller explanation elsewhere for complex information. For an image link, describe its target. See WordPress accessibility guidance on alternative text.
Informative images
Include the information readers need from the image, in the context of the article. For a photo illustrating a repair guide, name the relevant part or action rather than writing a generic inventory of everything in frame. Avoid phrases such as “image of” or “picture of” when they add no useful information.
Decorative images
An image is decorative when it adds no information or function—for example, a flourish used only to separate sections. Set its alt text to empty rather than describing its appearance. In the WordPress block editor, use the decorative control when available. Do not put a whitespace, a dash, or the word “decorative” in the alt field as a substitute for empty text.
Images with text
If an image contains words that matter and the same words are not written nearby, include the essential wording in the alternative. If the image is a poster or chart with substantial text, provide the full content in the page as well; alt text is not a good place for a long transcription.
Images that are links or controls
When an image is the only content inside a link, its alternative text should communicate what the link does or where it leads. “Search” is more useful than “magnifying glass” for a search control. If visible text already labels the same link, avoid announcing the same label twice; check the rendered result and the surrounding link markup.
Charts, diagrams, and other complex images
Use alt text to identify the image and its central point, then put the detailed data or relationships in adjacent text, a table, or a longer description. Do not force a multi-paragraph explanation into one alt attribute. This lets the main content remain available to everyone and easier to update.
2. Write and review the wording
- Identify the image’s purpose on this page: information, decoration, text, link, or complex content.
- Look at nearby headings, captions, and paragraph text. Do not repeat information the reader already gets from the same context unless needed to make the image’s purpose clear.
- Write a concise replacement for the information or action the image contributes.
- Check accuracy, including names, numbers, direction, and any claim inferred from the image.
- Read the paragraph with the alt text in place. Remove repeated or distracting phrasing and add any missing explanation to the page itself.
There is no single word count that works for every image. Prefer the shortest text that preserves the relevant meaning. Avoid keyword stuffing: alt text is an accessibility alternative, not a list of search terms. WordPress materials mention search visibility as a possible use, but the practical guidance here does not promise a particular search ranking effect.
3. Add alt text in the WordPress block editor
- Open the post or page in the block editor and select the Image block.
- Open the block settings sidebar if it is hidden.
- Find the Alternative text field and enter the description you chose. If the image is decorative, select “Mark as decorative” where that control is available.
- Save or update the post, then review the page in context.
Text entered in the Image block applies to that image in that post or page. Alternative text saved to the Media Library acts as the default when that media item is inserted elsewhere. WordPress documents these controls in its Image block documentation.
Set a Media Library default
In the WordPress dashboard, open Media Library and select the image to view its attachment details. Enter the alternative text in the image details, then save if your interface presents a save action. When you insert the media item elsewhere, WordPress can use that value as the default. Review the actual use each time: a default that fits one page may be wrong when the image has a different role or appears in a different link.
Featured images and theme output
A featured image can be rendered by the active theme or a plugin rather than by an Image block in the post body. Check the published page and, if needed, the rendered HTML to confirm that the output has the appropriate alternative text. Themes and plugins can change how media is displayed, so do not assume that editing one block updates every use of the same image.
4. Review AI-generated alt text
AI can suggest a starting description, but an editor should decide whether it is accurate and appropriate to the page. Check whether the suggestion:
- Correctly identifies the image without guessing at people, places, or events.
- Describes the detail that matters in this article, not just generic visible objects.
- Repeats information already stated nearby.
- Should instead be empty because the image is decorative.
- Needs a short alt value plus a fuller explanation in page text.
A model can miss context or misidentify what it sees. WordPress Learn presents generated alt text as a suggestion to evaluate, not a replacement for editorial review. See its AI alt-text lesson.
5. Validate the published result
- Confirm that informative images have a useful alternative.
- Confirm decorative images are skipped rather than announced with irrelevant descriptions.
- Confirm linked images communicate the link purpose.
- Read the surrounding text to catch duplicate announcements.
- For complex visual content, verify that the important information appears outside the alt field too.
- Check featured images and images inserted by patterns, templates, or plugins on the rendered page.
If you inspect HTML, a meaningful image might look like <img src="chart.png" alt="Bar chart showing requests rising from January through March">. A decorative image should have an empty attribute, such as <img src="divider.png" alt="">. The visual editor is usually the right place to enter the value; HTML inspection helps confirm what the published page actually contains.
6. Troubleshooting
| Problem | Likely cause | Fix |
|---|---|---|
| The image is announced as a filename. | The rendered image may lack an alt attribute, or a plugin or theme may be outputting a different image instance. | Inspect the published image output; set the alternative in the correct block or media field and check theme/plugin rendering. |
| The same image has different alt text on different pages. | Block-level alternative text is specific to that block use. | Edit each use to match its context. Set a Media Library default for future insertions, then review each insertion. |
| Decorative art is being announced. | The image has a non-empty description or the decorative control was not selected. | Mark it decorative or ensure the output uses alt="". |
| A chart’s alt text is very long. | The complete data explanation has been placed in the attribute. | Keep the alt concise and put the data or interpretation in a nearby paragraph or table. |
| AI supplied an incorrect description. | The model guessed from incomplete visual or page context. | Correct the wording manually, remove unsupported details, and decide whether the image is informative or decorative. |
| The Alternative text field is not visible. | The Image block may not be selected, or the settings sidebar may be closed. | Select the image block and open Settings. In Media Library, select the image to open its details. |
7. Capture an image for review
If you need a screenshot of a published page to inspect its layout or document how an image appears in context, a browser screenshot is a separate step from writing alt text. For a manual capture, open the page in a browser, set the viewport you need, and use the browser’s screenshot or print controls. A screenshot can help you review presentation, but it cannot determine whether the alternative text is accurate; inspect the page content and rendered image attributes too.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. Make one request to capture a page as an image; see the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://wordpress.org/documentation/article/image-block/ -o shot.webpScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots.
Sign up for 1,000 free screenshots a month, with no card required.
Frequently asked questions
Does every image need descriptive alt text?
Every image should have an appropriate alternative treatment. Informative images need a description; purely decorative images should have empty alternative text so assistive technology can skip them.
Should I include the image’s filename or title?
Only if it communicates the image’s relevant meaning. Filenames and media titles are not a substitute for a contextual alternative.
Should I put keywords in alt text for SEO?
Use words that accurately convey the image’s purpose in context. Do not add search terms that do not help someone understand the image or its function.
Can I use the same alt text everywhere an image appears?
Use the same wording only when the image serves the same purpose in each context. The right alternative can change when the surrounding text or link changes.
