Decide what each image contributes in its current context before writing alternative text.
Use concise contextual text for informative images. Use an empty alternative for decorative images.
WordPress Media Library text becomes an insertion default. Block edits apply only to that instance.
Start with image purpose
Alternative text replaces an image’s relevant purpose when the image cannot be perceived.
The same file can serve different purposes on different pages. Its text can therefore differ.
Do not describe pixels automatically. Explain the meaning or function needed here.
Use the W3C decision tree
The W3C alt decision tree separates informative, functional, decorative, and complex cases.
Ask whether the image contains text, performs an action, or contributes meaning.
Then decide between concise alt text, empty alt, or a longer equivalent.
Understand WordPress storage
WordPress can store alternative text with the media attachment. That becomes a reusable default.
An Image block also stores its current alt attribute inside the block’s saved markup.
These layers support reuse and context. They also create maintenance choices.
Use the Media Library default carefully
Write a sensible default when one description suits common uses of the file.
The WordPress Image block guide says that default carries into new insertions.
A media default cannot understand every future context. Review each inserted instance.
Use per-block overrides
Select the Image block and open its Content settings. Review Alternative text there.
Changing this value later affects only that page or post instance.
Use an override when surrounding copy changes the image’s purpose.
Do not assume later synchronisation
Existing Image blocks contain saved alt values. A later attachment edit may not replace them.
Audit existing instances after changing a Media Library default. Search and update deliberately.
Test the public HTML. Storage screens cannot prove every rendered instance.
Distinguish empty from missing alt
An empty `alt=””` tells assistive technology that the image contributes no replacement text.
A missing alt attribute can cause filenames or other fallback announcements.
Core Image blocks default toward an empty alt attribute. Still inspect plugin output.
Write informative image text
State the image information needed for the page’s purpose. Keep it concise.
A portrait may need the person’s name. A product image may need distinguishing details.
Do not describe irrelevant colours or scenery. Context decides useful detail.
Write functional image text
When an image acts as a link or button, describe its destination or action.
“Search” communicates an icon button’s function. “Magnifying glass” describes only appearance.
Avoid repeating adjacent link text. The combined accessible name should remain concise.
Use empty alt for decoration
Decorative images add visual styling without needed information. They usually need `alt=””`.
Do not write “decorative flourish.” That creates needless interruption rather than an alternative.
Confirm the image truly adds no meaning or function. Decoration is contextual.
Use empty alt for redundancy
An image can repeat nearby text completely. Repeating that text again creates noise.
Use an empty alternative when the same information already appears accessibly nearby.
Check whether any unique image detail still matters. Do not assume redundancy casually.
Handle images containing text
If essential text appears only inside the image, include that text appropriately.
Prefer real HTML text wherever possible. It resizes, reflows, and adapts better.
If nearby real text already repeats everything, the image can use empty alt.
Handle screenshots
A screenshot can show interface location, state, error, or result. Describe the relevant point.
Do not transcribe every visible menu item. Nearby instructions should carry the procedure.
For critical interface text, provide it as real text nearby.
Handle charts and diagrams
Complex images contain relationships that concise alt text cannot express fully.
Use brief identification in alt text. Provide the complete insight or data nearby.
Link towards a data table or long description when appropriate. Keep it discoverable.
Handle logos
A standalone logo often needs the organisation or product name. Context can add function.
A linked homepage logo may need only the home destination name.
Do not add “logo of” automatically. The useful identity usually matters more.
Handle portraits and people
Name the person when identity matters. Add role only when context requires it.
A decorative team photograph may need empty alt when nearby names provide meaning.
Avoid subjective appearance judgements. Describe relevant, objective information.
Handle product images
Name the product and visually distinguishing attributes needed for selection.
Several views need different text when each reveals unique information.
Do not repeat a long product title mechanically. Focus on the image’s contribution.
Handle image links
When the image alone forms a link, alt text becomes its accessible name.
Describe the destination purpose. Avoid visual descriptions that hide navigation intent.
If visible text shares the link, prevent a noisy duplicate name.
Handle Gallery blocks
Review every gallery image independently. One generic description cannot cover the set.
Repetitive decorative thumbnails can create excessive announcements. Purpose determines each alternative.
Test lightbox links and captions too. Plugin output can change accessible names.
Handle Cover blocks
Cover media often acts as decorative background behind real text. Its purpose may be visual.
If the media conveys essential information, provide that information through accessible page content.
Inspect rendered markup. Background and foreground media can receive different treatment.
Handle Media and Text blocks
Compare the image with adjacent text. The copy may already provide its complete meaning.
Use empty alt for full redundancy. Add only unique useful image information otherwise.
Review mobile stacking. Context should remain understandable after the visual order changes.
Handle featured images
Featured images can appear on single posts, archives, cards, and social previews.
Their purpose changes by template. Theme output may use attachment alt or another label.
Inspect every important placement. A Media Library default may serve only some contexts.
Separate alt text from captions
A caption is visible to everyone. It can add attribution, explanation, or context.
Alt text replaces relevant image meaning. It need not repeat the caption.
Read both together. Remove avoidable duplication while preserving complete information.
Separate alt text from titles
The Image block can expose a Title attribute. It is not an alt substitute.
WordPress documentation notes many devices and browsers do not display title text.
Do not hide essential meaning there. Use appropriate visible content and alt text.
Separate alt text from descriptions
Media attachment descriptions can support library management or attachment pages.
They do not automatically become the Image block’s alt attribute.
Store each field for its real purpose. Do not duplicate content blindly.
Avoid “image of” openings
Assistive technology already identifies images. “Image of” usually adds no information.
Exceptions can exist when medium matters. A photograph and illustration may carry different evidence.
Begin with the relevant subject or function. Keep the wording direct.
Avoid keyword stuffing
Alt text exists for an equivalent, not a hidden keyword list.
Repeated phrases create noise and misrepresent image purpose. Write naturally and specifically.
Useful page content supports discovery better than inaccessible manipulation.
Avoid filenames as alternatives
Camera filenames and asset codes rarely explain meaning. Replace them with contextual decisions.
A meaningful filename can still be awkward user-facing text. Review it manually.
Missing alt can expose filenames unexpectedly. Inspect the actual rendered attribute.
Keep alternatives concise
Use enough words to communicate purpose. Remove detail available elsewhere.
No universal character limit decides quality. Context and complexity control the necessary length.
Move long explanations into visible page content. Everyone can then use them.
Create an insertion workflow
- Choose the final image.
- Identify its page purpose.
- Review nearby content.
- Choose informative, functional, or empty alt.
- Edit the block instance.
- Preview the public context.
- Inspect the rendered alt attribute.
- Record complex-image equivalents.
Do this during authoring, not after publication. Context is clearest then.
Create a reuse workflow
When selecting existing media, read its default before insertion. Do not accept automatically.
Compare the new page purpose with earlier use. Override whenever meaning differs.
Use empty alt when the reused image becomes decorative here. Reuse does not preserve purpose.
Audit existing content
Inventory rendered images across representative templates. Flag missing, empty, and suspicious repeated values.
An empty alt is not automatically defective. Review decorative intent before changing it.
Prioritise functional images, complex images, and high-traffic workflows. Their failures have greater impact.
Test with images unavailable
Disable image loading or inspect the accessibility tree. Read the page without visuals.
Confirm information, links, and actions remain understandable. Decorative images should disappear quietly.
Then test with a screen reader. Visual absence alone provides incomplete evidence.
Test plugin image blocks
Gallery, slider, testimonial, logo, and card blocks can render images differently.
Check whether each block exposes per-instance alt controls and empty alternatives.
Inspect public HTML after updates. Plugin settings can change markup ownership.
Plan plugin deactivation
Alternative text may live inside block attributes or plugin data. Export before migration.
Convert a sample on staging. Confirm images and correct alt attributes survive.
Keep revisions until the full audit passes. Silent loss can affect many instances.
Review image replacement
Replacing an Image block can preserve wording written for the previous file.
Review alternative text immediately after replacement. Similar subjects can still convey different information.
Also review captions, links, and nearby references. The complete context may need revision.
Review cropping and focal points
Cropping changes what sighted users receive. Existing alt text may describe removed details.
Check responsive crops and focal points. Each breakpoint can emphasise different content.
Keep the alternative aligned with the rendered image’s meaningful contribution.
Translate alt text contextually
Translated pages need alternatives in their page language. Preserve names and technical labels accurately.
Do not reuse the source-language attribute automatically. Review cultural and contextual differences.
Translate nearby long descriptions too. One localised sentence cannot replace untranslated data.
Define contributor responsibility
The person selecting an image usually understands its intended purpose best.
Require that contributor to choose treatment during insertion. Editors can review before publication.
Do not leave every decision for a later accessibility audit. Context disappears quickly.
Review generated suggestions critically
Automated suggestions can identify objects while missing page purpose, humour, or function.
Treat generated text as a draft. A human should compare context and accuracy.
Never publish invented identities or details. Remove irrelevant visual catalogues.
Use bulk edits cautiously
Bulk attachment edits can improve future defaults. They may not repair existing block instances.
Search saved block markup before promising complete coverage. Sample public pages afterwards. We work through it in cross-browser testing for block pages.
Never fill empty alternatives automatically. Many empty values are deliberate and correct.
Review cached output
Page caches can preserve earlier alt attributes after block corrections. Purge relevant layers.
Fetch the anonymous public response. Inspect the exact image element again.
Content delivery transformations may alter markup. Verify the final delivered page.
Maintain an exception record
Some complex images need planned long descriptions or replacement work. Record those gaps.
Assign an owner, severity, workaround, and review date. Do not hide unresolved barriers.
Close the record after rendered verification. A Media Library edit alone is insufficient.
Know when alt text adds harm
Decorative and fully redundant images usually need empty alternatives. Descriptions add repeated noise.
A keyword-rich description can also misstate function. More words are not more accessible.
This is the honest weak case. Use empty alt deliberately when context warrants it.
Use the alt-text workflow checklist
- Identify the image purpose.
- Review surrounding content.
- Choose informative, functional, or decorative treatment.
- Use empty alt deliberately.
- Write concise contextual wording.
- Provide complex information nearby.
- Review Media Library defaults.
- Override individual blocks when needed.
- Avoid captions and title duplication.
- Test linked-image names.
- Inspect the rendered attribute.
- Audit reused instances.
- Test plugin image output.
- Plan migration and deactivation.
Frequently asked questions
Does Media Library alt text update every existing Image block?
Do not assume so. Existing blocks store their current alt values separately.
Should decorative WordPress images have alt text?
They should usually carry an empty alt attribute rather than descriptive text.
Should alt text repeat an image caption?
Usually not. Read both together and remove unnecessary repeated information.
What should linked-image alt text describe?
Describe the link destination or action, not merely the image’s appearance.
How should WordPress charts use alt text?
Use brief identification, then provide complete insights or data nearby.
The verdict
Core Image blocks expose per-instance alternative text. Test plugin blocks before adoption. Then compare the $299 lifetime suite when several Pro blocks preserve your image workflow.
Leave a Reply