Write in Google Docs. Publish with Tenwrite.

Publish to WordPress or Blogger, manage updates, and track search performance.

Start free 5 free exports · No credit card required

Add Image Alt Text in WordPress and Check It Saved

Abstract representation of an image description and a saved-result checklist in a publishing system.

To add image alt text in WordPress, select the image in the block editor, enter a description in its Alternative Text field, and save the post. Then check the saved image in the article—not just the field you edited.

The description should explain what the image contributes in that particular article. A screenshot used to demonstrate one setting may need different alt text when the same screenshot illustrates another setting. This guide follows an illustrative screenshot from an editor’s notes through a saved-result check.

The quick answer: where to add image alt text for WordPress

Open the post, select its Image block, and look for Alternative Text in the block settings. Enter the text, save the draft or update the post, and check the resulting placement. You can also edit an attachment’s alternative text in the Media Library, but check images already placed in articles separately.

Alt text is a text alternative for an image. It can be used by screen readers and may appear when an image cannot be displayed. It is not the same field as a caption or an image title:

FieldWhat it doesExample for a settings screenshot
Alternative textConveys the image’s relevant information or purpose when the image cannot be seen.“Discussion settings with Allow comments on new posts enabled”
CaptionAdds visible text near the image for all readers.“Check the discussion settings before publishing.”
Image titleIdentifies the image in WordPress or supplies a title attribute in some contexts; it is not a substitute for alt text.“Discussion settings”

A caption can add context, but it does not automatically replace the image’s alternative text. Likewise, a useful title in the Media Library does not prove that the image in the article has useful alt text. The exact controls can differ for galleries, custom image components, or other editor configurations.

Choose alt text from the image’s purpose, not just its appearance

Before writing, ask: What would a reader miss here if they could not see the image? The answer depends on what the article uses the image to communicate, not just on what the file contains.

Consider this illustrative example: one screenshot shows a WordPress settings screen with Allow comments on new posts enabled and Comment author must fill out name and email enabled. The screenshot is fictional; the descriptions show an editorial decision, not a tested WordPress result.

Image purposeSurrounding textProposed alt textWhy this fits
Show that comments are enabledAn article explains where to turn on comments for new posts.“Discussion settings with Allow comments on new posts enabled”It identifies the setting relevant to this article.
Show the author-information settingA different article explains what commenters are asked to provide.“Discussion settings with Comment author must fill out name and email enabled”The same screenshot now supports a different point.
Add decoration onlyA decorative image separates sections without adding information.Leave the alt value empty intentionally.A description would add content the reader does not need.
Introduce a complex imageAn article discusses a chart with several values and a trend.Briefly identify the chart; explain its essential values and conclusion in nearby text.A short alternative alone may not convey all the information needed to understand the chart.

For an informative screenshot, name the relevant control and state if its visible setting matters. You usually do not need to describe every menu and icon. If the surrounding text already explains a detail, avoid copying a whole paragraph into the alt field; focus on the image’s contribution.

For a purely decorative image, an intentionally empty alternative tells assistive technology that there is no image information to announce. An image is not decorative just because it is attractive: if it contains a meaningful instruction, label, or result, that information needs an appropriate text alternative. For linked images, consider the link’s purpose as well as the picture.

Two weak descriptions for the illustrative screenshot show why context matters:

  • settings-screenshot-final-2.png is a filename, not an explanation. It does not tell the reader which setting matters.
  • “WordPress image alt text WordPress guide best WordPress settings SEO” repeats search terms without describing the image. A keyword belongs only if it naturally helps explain the image.

Keep wording direct and accurate. There is no single character count that makes every description useful. If the image carries more information than a concise description can reasonably convey, put the important details in the article too.

Add and save alt text in the WordPress block editor

Use this route when the image is already in the post. The following steps use the illustrative comments screenshot and the first article context.

  1. Open the post for editing. Find the screenshot in the article section that explains enabling comments. Confirm that the image itself shows the setting you plan to describe.
  2. Select the image. Click the image in the editor. If you select a surrounding group or gallery instead, select the individual Image block within it. The block name and available settings help you tell what is selected.
  3. Open the block settings. If the settings sidebar is closed, open it and choose the block settings. Look for the field labeled Alternative Text or similar wording. Your editor’s layout may differ.
  4. Enter the description. For this illustrative placement, enter: “Discussion settings with Allow comments on new posts enabled.” Do not put it only in the caption or title field.
  5. Save the post. Save the draft or update the published post using the available control. If you are not ready to change a live article, work in a draft or follow your site’s review process.
  6. Reopen the image settings. Select the same image again and confirm the intended wording remains. Then check the preview or published placement.

If the sidebar does not offer an alternative-text field, first make sure the individual image is selected. A custom block or component may have different controls; use its available image settings or ask the person who maintains the site. Do not assume a caption field performs the same job.

For the second illustrative article, use the description about the name-and-email setting instead. The image file may be the same, but the purpose in the article is different. Check each placement on its own merits.

Use the Media Library without assuming existing placements changed

The Media Library provides another place to enter alternative text for an image attachment. It is useful when you are preparing an image before adding it to a post, or when you need to review the information stored with the attachment.

  1. In WordPress, open Media and find the image. Use its thumbnail, filename, and attachment details to distinguish it from similar files.
  2. Open the attachment details and find Alternative Text.
  3. Enter a description appropriate to the intended use, or leave it empty when the image is purely decorative. Save the change if your screen requires it.
  4. When you insert the image, select it in the post and check the alternative-text field for that placement. Adjust the wording if the article calls attention to a different detail.

A library description can be a useful starting point, but it is not proof that every existing use of the attachment has changed. Existing blocks and other image components can behave differently. If you are correcting an image already in an article, reopen that post, select the affected placement, save any necessary correction, and inspect the saved result.

This distinction matters for the illustrative screenshot: a general library description might identify the settings screen, while each article needs the particular control relevant to its instructions. Do not rely on a single library edit as a substitute for checking both articles.

Carry an image’s intended description from document to WordPress

When an article starts in a document, record the image decision alongside the editorial source. The note is a reminder for the publisher, not evidence that WordPress received or saved the description.

Here is an illustrative note sheet you can copy and adapt. Keep it outside the reader-facing article text.

Image identifierPurpose in the articleProposed alt text or decision
Settings screenshot, after “Enable comments”Show that comments are enabled for new posts.“Discussion settings with Allow comments on new posts enabled”
Decorative divider, before the conclusionSeparate sections visually; convey no information.Empty alt value.
Results chart, after the results paragraphIntroduce a comparison explained in the paragraph.Identify the chart briefly; include the meaningful figures and conclusion in the article text.

After the article becomes a WordPress draft, find the first image by both its content and its location after the relevant heading. Select it and compare its actual Alternative Text field with the note. Enter or correct the wording if necessary, save, and verify the placement. Repeat for the other images; a decorative decision and a chart description need different checks.

If a screenshot is absent, fix the missing image before checking its alt text. For a document that began in Google Docs, the guide to fixing images not showing in WordPress covers that separate problem. If you publish from Markdown and review the draft, include the same image-by-image check in your review.

A transfer method may move article content into a draft, but the note in the source document does not establish what the final image contains. Verify the saved WordPress placement instead.

Review AI-generated alt text before using it

An alt text generator for images can suggest a starting description. It cannot be relied on to know which detail matters in your article, and its wording may describe something incorrectly. Review a suggestion against both the image and the surrounding text before entering it.

For example, imagine a generator suggested this for the fictional settings screenshot. This is an invented suggestion, not output from a tested tool:

“A WordPress dashboard showing user profiles and several SEO settings.”

For the article about enabling comments, the contextual revision would be:

“Discussion settings with Allow comments on new posts enabled.”

The revision removes claims about user profiles and SEO settings that the example does not establish. It also identifies the setting the reader needs for the article.

Before accepting any suggestion, check:

  • Objects and labels: Are the controls, names, and states actually visible? Remove invented details.
  • Article relevance: Does the text include the detail this section uses the image to explain? Add it if it is missing.
  • Keywords: Do any search phrases describe the image naturally, or have they been added without helping the reader?
  • Redundancy: Does the description repeat surrounding text unnecessarily or list irrelevant visual details?
  • Purpose: Is the image informative, or is an empty value more appropriate because it is purely decorative?

Edit the suggestion yourself, then put the reviewed wording in the appropriate WordPress field. A plausible sentence is not a substitute for checking the saved image.

Check the saved article’s actual image

Typing into a field is only part of the task. The correct image in the saved article should carry the intended alternative, or an intentionally empty value for a decorative image.

First save the post, then reselect the image in the editor. Confirm that the field still contains the wording you chose. Open the saved preview—or the published page if the change is live—and find the same image in its article context. Make sure the image loads and appears in the intended section. A visual preview alone does not reveal the alt value; browser inspection can help you check it.

Optional: inspect the image’s alt attribute

In many desktop browsers, you can right-click the image in the preview or published page and choose Inspect. In the developer tools, find the selected image’s <img> element and look for its alt attribute. The exact browser interface varies.

These examples are illustrative:

alt="Discussion settings with Allow comments on new posts enabled"

This is a descriptive value. Compare it with your intended wording and the image’s role in the article.

alt=""

This is an explicitly empty value. It can be appropriate for a purely decorative image. Confirm that empty was the editorial decision, rather than assuming it means someone completed the check.

<img src="example-image.png">

This example has no alt attribute. That is different from an intentionally empty one. Return to the relevant image settings and investigate how the component outputs the image.

For the worked example, use this pass/fail check:

  • Correct placement: The screenshot is in the section about enabling comments, not just elsewhere in the post.
  • Correct image: It shows the comments setting described in the note.
  • Saved setting: After reopening the block, the Alternative Text field contains the chosen description.
  • Reader-facing output: If you inspect the preview or published image, its alt value matches that description.
  • Useful meaning: The wording identifies the relevant enabled setting rather than a filename or a list of keywords.

If any item fails, correct that placement and repeat the check after saving. Inspecting an attribute is a useful basic check, not a complete accessibility audit. If you cannot inspect the output yourself, ask someone who maintains the site to help verify it.

Fix missing, unchanged, or unhelpful alt text

Start with the affected image and article. These are possible explanations to check, not diagnoses of your site.

SymptomNext check and action
The field appears empty or belongs to another image.Select the individual image rather than its surrounding group or gallery. Compare the thumbnail and article location with your note, enter the intended wording, save, and recheck that saved image.
You edited the Media Library, but an article still has old wording.Open the affected post and select its image placement. Change its alternative text if needed, save the post, and recheck that placement in the preview or published page.
Your correction disappears after you leave the editor.Reopen the post and verify that the change was saved or updated. Enter it again if necessary, save, then reselect and inspect the same saved image.
The image has no familiar Alternative Text field.Check whether it is an individual Image block or a custom component. Look for that component’s image settings or ask the site maintainer; after a correction, recheck its saved output.
The field contains a filename, generic description, or AI wording that misses the point.Compare the image with the nearby article text. Replace the wording with the relevant description—or make an intentional decorative decision—save, and recheck the affected image.
The editor field looks right, but the inspected page still shows an old value.Confirm you are viewing the right post and image, and that the change was saved. Reload the preview or page; if the mismatch persists, ask the site maintainer to investigate how that placement is rendered, then inspect it again.

For your next WordPress draft, choose one image and write its description from the section’s purpose. Enter it, save the post, and use the saved-image checklist to confirm that the actual placement carries the intended value.