To add alt text in WordPress, open Media → Library, select an image, enter a concise description in the Alt Text field, and save the media record. You can also set it for an individual use of an image from the Alternative text control in the Image block. The right wording depends on what the image does on that particular page: describe meaningful content, describe the purpose of a linked image, and leave purely decorative images blank so WordPress outputs alt="".
Antihost offers managed WordPress hosting with free migration, one-click staging and a 14-day free trial.
What image alt text is—and what it should accomplish
Alt text is the text alternative associated with an image. It gives the page a useful equivalent when the image cannot be perceived and helps preserve the image’s meaning in the surrounding content. WordPress labels the Media Library field “Alt Text – (Image files only) The alt text for the image … Used for accessibility.” The important question is not “What objects are visible?” but “What information or function does this image provide here?”
As an Amazon Associate I earn from qualifying purchases.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
A reliable practical test comes from WordPress’s documentation style guidance: imagine replacing the image with the text of its alt attribute. If the page would lose meaning, the text is incomplete. If the page would gain a repeated sentence or an irrelevant description, the text is doing too much. Alt text is therefore contextual, not a permanent caption that can be copied unchanged into every placement.
WordPress accessibility-ready guidance requires a non-decorative img element to have an alt attribute, while a decorative image should have an empty one. W3C technique guidance likewise calls for a short text alternative when using an img element. WordPress core and official plugins are expected to conform to WCAG 2.2 Level AA through WordPress coding standards. These requirements explain why an empty value for a decorative image is intentional, not an omission.
#1 Best Overall
Decide what kind of image you have before writing
Classify the image by its job in the page. The same file can need different alt text in two locations: a product photo used as a link needs functional wording, while the same photo beside a detailed paragraph may need an informative description. Use this decision table before opening a field.
| Image purpose | What the alt text should convey | Typical treatment |
|---|---|---|
| Informative | The meaningful subject, action, result, or relationship that the image adds to the page. | Write a concise description tied to the surrounding content. |
| Functional | What happens when someone activates the image, rather than a list of visual details. | Describe the destination or action of the link or control. |
| Decorative | Nothing; the image adds no information and has no independent function. | Leave the field blank so the markup is alt="". |
| Featured image with no link | What the image depicts when the image itself is part of the visible content. | Describe the image in the featured-image field or Media Library record. |
| Featured image that links to the post | The destination represented by the link. | WordPress theme guidance recommends the post title as the alt text. |
Do not force a descriptive sentence onto a decorative graphic. Conversely, do not leave a meaningful image blank merely because a caption appears nearby. The image’s role and the page’s reading order determine the answer.
Add alt text to an image that is already uploaded
The Media Library method updates the attachment record and is the most direct route when the image already exists in your site’s media collection.
- Sign in to the WordPress dashboard.
- Open Media → Library.
- Select the image. WordPress opens its attachment details panel.
- Locate the Alt Text field.
- Enter wording based on the image’s purpose in the page where it will be used. Keep the field empty if the image is purely decorative.
- Save the media record using the save or update control shown in the attachment panel.
After saving, return to the post or page that uses the image and check the image there. A media attachment can appear in more than one context, so a globally stored description may need to be adjusted for a particular use. If the image functions as a link in one location and as supporting content in another, verify that the rendered result communicates the correct role in each location.
Add or change alt text while editing a post or page
You can set the text at the point where an image is inserted or edited. This is useful when the surrounding paragraph changes the image’s meaning or when you need to review a page’s images one by one.
- Open the post or page in the WordPress editor.
- Insert an image or select an existing image in the content.
- Make sure the selected block is the Image block, not a surrounding group, column, or gallery block.
- Find the block’s Alternative text control.
- Write the description that preserves the image’s purpose in this specific placement.
- Leave the control blank when the image is decorative.
- Save the post as a draft or update the published page, according to your normal publishing workflow.
Review the text against the final layout, not just the upload dialog. A photograph used as evidence in one paragraph may be an incidental visual in another. The editor’s alternative-text control is the place to resolve that page-level context.
Set the correct text for featured images
Featured images require one extra question: is the image itself linked to the post?
When the featured image is unlinked
Describe what the image shows when it contributes visible information on the page. For example, if an article’s unlinked featured image depicts a cracked phone screen, the alt text can identify that subject concisely. Do not write a generic filename or a string of visual details that the page does not need.
When the featured image links to the post
When selecting the image takes the reader to the post, the link’s purpose matters more than a visual inventory. WordPress theme guidance recommends using the post title as the alt text for a linked featured image. This gives the image link the same destination label that a text link would provide. Check the title in its final, published wording before saving the field.
When a theme supplies the image automatically
A theme may output a featured image without exposing an Image block in the editor. In that situation, edit the attachment’s Alt Text field in Media → Library, then inspect the post’s rendered output. If the theme changes the image’s link state or supplies its own accessible label, resolve the result in the theme or template settings rather than adding a second, competing description in the article body.
Leave decorative images empty
An image is decorative when removing it would not remove information, change an instruction, or alter the meaning of the page. Common examples include a flourish between sections, a purely visual background treatment implemented as an image, or an icon that repeats a nearby text label and has no separate action.
For a decorative image, do not type “decorative,” “image,” a filename, or a single space into the field. Leave the alternative-text field blank. WordPress should then produce an empty attribute, alt="". The empty value tells assistive technology that the image has no additional information to announce, allowing the reader to continue to the useful content.
Re-evaluate the classification if the image becomes clickable, conveys status, identifies a person or place, illustrates a step, or supplies evidence for a claim. A graphic can be decorative in one component and informative in another; classify it each time its role changes.
Write concise, useful alt text
Good alt text is specific enough to replace the image’s meaning but short enough to fit naturally into the page’s reading order. Start with the information a reader needs, then remove details that do not affect interpretation.
Name the subject and relevant action
Identify the central subject and an important action or relationship when those details matter. “Technician replacing a laptop battery” communicates more than “laptop photo.” If the page explains a before-and-after result, include the state that the image demonstrates rather than listing every visible object.
Use the surrounding context
An image beside a paragraph about a specific component does not need to repeat every component visible in the frame. Conversely, an image used to distinguish two similar products may need the model or distinguishing feature. Read the heading, paragraph, caption, and link label before finalizing the text.
Avoid filename-like wording
Names such as IMG_4821.jpg, camera-generated sequences, and strings of keywords do not preserve meaning. Write normal language. You generally do not need to begin with “image of” or “picture of”; the page already identifies the content as an image. Use that space for the subject, action, or function.
Do not duplicate nearby text
If a caption or adjacent sentence already provides the same information, do not repeat it word for word in the alt text. Add the part of the image that the surrounding text does not supply, or use a concise alternative that lets the reader move through the page without hearing the same sentence twice.
Free tools Windows power users keep installed
One-click scans. No signup required.
Include words visible in the image only when they matter
If text inside the image is essential to understanding the page, represent that information in the alternative text or in the surrounding page copy. If the words are merely a logo or decoration already identified by nearby text, repeating them may add noise. The replacement test decides which case you have.
Examples by purpose
The examples below show how a single visual idea can receive different wording depending on its role. They are patterns, not phrases to paste into every page.
| Context | Weak or misleading entry | More useful alternative |
|---|---|---|
| A tutorial image showing a hand connecting a USB cable to a phone | phone.jpg |
“Hand connecting a USB cable to the phone’s charging port” |
| A thumbnail linking to an article titled “How to Reset a Router” | “Router with blinking lights” | The post title, “How to Reset a Router” |
| A decorative divider between two headings | “Blue line divider” | Leave blank: alt="" |
| A chart image whose surrounding paragraph already states the trend, with the chart adding no further information | A paragraph-length transcription that repeats the surrounding copy | Leave blank if it is genuinely redundant, or add only the distinct data relationship the chart contributes |
| An unlinked featured image showing a cracked phone screen | “featured-image-final-2.png” | “Cracked phone screen with a spiderweb pattern across the glass” |
The final example is informative only if the crack is relevant to the article. If the post is about an unrelated software setting and the photograph is merely a visual accent, it may be decorative instead.
Review AI-generated suggestions before saving
Some WordPress media editors can offer an AI-generated suggestion. Treat it as a draft, not as an accessibility decision. Automated descriptions can identify objects while missing the action, the reason the image appears, or the destination of a link.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match- Check names and identities. Correct people, products, places, and other proper names; omit an identity the image does not establish.
- Check objects and actions. Confirm that the suggested object is actually visible and that the described action is accurate.
- Check relevance. Remove details that do not help explain this page’s point.
- Check the link purpose. For a linked image, replace a visual inventory with the destination or action when appropriate.
- Check decorative status. If the image adds no information, discard the suggestion and leave the field empty.
- Check nearby wording. Rewrite duplicated or contradictory text so the page reads once, clearly.
Only save the suggestion after it passes the same contextual test as manually written text. An accurate object label can still be the wrong alternative if the image’s function is to activate a link or if the graphic is purely decorative.
Check the result after saving
Saving a field is not the same as verifying the page. Use a short review after adding or changing text.
- Open the post or page preview, or view the published page.
- Confirm that the image appears in the intended location and has the intended link behavior.
- Read the alt text alongside the heading, caption, and surrounding paragraph. Remove repetition or fill in missing meaning.
- For a decorative image, confirm that the field remains empty rather than containing a filename or a space.
- If your team checks rendered HTML, confirm that a meaningful image has an
altattribute and that a decorative image usesalt="". - Repeat the check for templates that display the same attachment elsewhere, especially archives and featured-image cards.
Troubleshoot common WordPress alt-text problems
The Alt Text field is not visible
Confirm that you selected an image attachment in Media → Library, not a folder, filter, or another media type. In the editor, select the image itself and verify that the block toolbar identifies it as an Image block. A gallery, column, or group selection exposes different controls.
The text appears in the editor but not on the page
Save or update the post after changing the Image block’s Alternative text control. Then inspect the rendered page. A theme or block pattern may be outputting a separate copy of the image, so check the attachment record and any featured-image settings as well.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →A decorative image is announced
Reopen the image’s field and remove every character, including accidental spaces. The intended result is an empty value, alt="", not the word “decorative.” If the image is inserted by a theme or plugin, inspect that component’s own image settings because the editor field may not control the generated markup.
The same image needs different wording in different places
Decide which placement controls the meaning. Use the Image block’s page-specific alternative text when editing content, and review the Media Library value for templates or other automatic placements. If a single attachment is reused with genuinely different functions, document the intended wording for each component and verify the final output in context.
A linked image has a visual description but no clear destination
Rewrite the text around the link’s purpose. For a linked featured image, use the post title as recommended by WordPress theme guidance. For another linked image, describe what activating it does or where it leads, provided that destination is clear from the page.
A repeatable workflow for editors and site owners
Teams can make alt-text decisions consistent without turning them into a keyword-writing exercise. Apply this sequence whenever an image is uploaded or reused.
Recommended Free Tools
- Identify the role. Mark the image informative, functional, or decorative before writing.
- Read the placement. Review the heading, paragraph, caption, and link state around the image.
- Draft the replacement. State the key subject, action, relationship, or destination in ordinary language.
- Trim and compare. Remove filenames, generic openings, irrelevant details, and duplicated nearby text.
- Enter it in the correct control. Use the Media Library for an attachment, the Image block for a page-specific use, and the featured-image setting for a template-driven image.
- Save and render. Update the content, then check the page as a reader encounters it.
- Recheck after redesigns. A change from an unlinked image to a linked card, or from an article image to a decorative banner, can change the correct alternative text.
This workflow also prevents a common mistake: treating alt text as a hidden caption that can be written once and ignored. Its wording is part of the content design and should change when the image’s purpose changes.
How alt text differs from captions and surrounding copy
A caption is visible to everyone and can provide attribution, date, context, or commentary. Alt text is the replacement for the image’s meaningful contribution when the image itself is not available. They can complement each other, but they should not automatically match.
For example, a caption might identify a location and photographer, while alt text identifies the action that the article is explaining. If the caption already gives the only information the image contributes, repeating it may be unnecessary; if the image adds a distinct visual relationship, include that relationship in the alternative text. Always apply the replacement test to the combined page, not to the image in isolation.
WordPress accessibility guidance in practice
WordPress’s Theme Handbook states that decorative images included with img elements should have an empty alt attribute: alt="". WordPress documentation also describes the Alt Text field as an accessibility feature, and its style guidance says that replacing every image with the text of its alt attribute should not change the page’s meaning. W3C guidance similarly recommends a short text alternative for an img element.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesThese statements lead to two practical rules: every meaningful image needs a useful alternative, and every decorative image needs an intentionally empty one. A field filled with a filename satisfies neither goal. The quality check is semantic—whether the page’s information and functions survive without the image—not whether a particular number of words or keywords appears in the field.
Quick Recap
Quick decision checklist
- Does the image add information? If yes, describe that information.
- Does activating the image perform an action or open a destination? If yes, describe the function; for a linked featured image, use the post title.
- Does the image add nothing beyond decoration or repeated text? If yes, leave the field blank so the result is
alt="". - Would replacing the image with your wording preserve the page’s meaning?
- Have you removed filenames, irrelevant visual details, and duplicated nearby wording?
- Did you verify the final link state and rendered page after saving?
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
