April 14, 2020 · reala11y team

How to Write Effective Alt Text in WordPress

A practical guide to alt text in WordPress: what to include, decorative vs meaningful images, when to use empty alt, and the common mistakes to avoid.

Alt text is the single most common accessibility issue automated scanners flag, and one of the few that authors can almost always fix themselves. It is also widely misunderstood. WordPress puts an Alternative Text field on every image in the Media Library and the block editor, but a field is not guidance, and a lot of well-meaning alt text actively makes pages worse.

This is the practical version: what to write, when to write nothing, and the mistakes that show up most often.

What alt text is actually for

Alt text (WCAG Success Criterion 1.1.1, Non-text Content) is the text alternative a screen reader announces in place of an image. It also surfaces when an image fails to load and feeds search crawlers. The job is to convey the image’s purpose in context — not to describe every pixel.

The same photo can need completely different alt text depending on where it sits:

• In a gallery of product shots: Red ceramic mug, side view
• As the only illustration of a how-to step: Hand pressing the espresso tamper flat against the portafilter
• As a decorative header behind a heading: empty alt (more on that below)

Context decides the words. That is why no tool — ours included — can write perfect alt text unattended; it can draft, but a human confirms intent.

Decorative vs meaningful images

Before writing anything, decide which kind of image you have.

Meaningful images carry information the surrounding text does not: charts, diagrams, product photos, screenshots, photos of people the article is about. These get descriptive alt text.

Decorative images add visual texture but no information: background flourishes, divider lines, a generic stock photo of a laptop next to a paragraph that already says everything. These should have an empty alt attribute so assistive technology skips them.

A useful test: if you read the page aloud and the image’s content is already covered by nearby text — or the image is purely ornamental — it is decorative.

When to use empty alt

Empty alt means alt="" — the attribute is present but deliberately blank:

<img src="divider.svg" alt="">

This tells a screen reader “skip this, it’s decorative.” It is not the same as omitting alt entirely. A missing attribute makes some screen readers read out the file name (IMG_4821.jpg), which is noise. In WordPress, leave the Alternative Text field blank for decorative images, but make sure your theme or blocks still emit alt="" rather than dropping the attribute.

reala11y flags images that are missing the alt attribute and treats a present-but-empty alt as a deliberate decorative choice — it does not nag you to fill it in. See our WCAG 2.2 guide for how 1.1.1 fits the wider rule set.

What to include in good alt text

For meaningful images:

• Be specific and concise. One sentence is usually enough; aim for roughly 125 characters or fewer so screen readers don’t truncate awkwardly.
• Lead with what matters. Bar chart: mobile traffic overtook desktop in Q3 beats A chart showing data.
• Match the purpose. A linked image’s alt should describe the destination, not the picture, since it functions as a link.
• Skip “image of” / “photo of.” Screen readers already announce the element as an image. The words are redundant.
• Put complex detail in the body. For a dense diagram or data table, write short alt text and place the full explanation in visible text or a caption nearby.

Common mistakes

These are the patterns that come up again and again in real WordPress sites:

• Stuffing keywords. Alt text is not an SEO dumping ground. cheap wordpress hosting fast wordpress hosting best hosting helps no one and reads as spam to assistive tech.
• Repeating the caption. If a visible caption already describes the image, duplicating it in alt text means the content is announced twice.
• Using the file name. DSC_0042 is not a description.
• Describing decoration. Decorative swirl is worse than alt="" — it forces screen-reader users to hear noise.
• Putting alt on the wrong field. WordPress also has Title, Caption, and Description fields. Only Alternative Text becomes the alt attribute. (The redundant title attribute is a separate issue reala11y can strip at the code level.)
• Auto-generated boilerplate. Some plugins backfill alt text from the file name or post title across the whole library. That satisfies a scanner’s “attribute present” check while telling users nothing.

That last point matters: passing an automated check is not the same as being understood. Automated tooling typically detects only 30–40% of WCAG issues by criteria — it can tell you an alt is missing, but it cannot judge whether the words you wrote are right. That judgment is human.

How reala11y helps

reala11y is a code-level tool, not an overlay widget — it fixes the underlying HTML rather than layering JavaScript over it. For alt text specifically it:

• Scans your published content and flags <img> elements missing an alt attribute (rule R002, WCAG 1.1.1).
• Lets you search the Media Library by alt-text content, so you can find images that were never described.
• Offers optional bring-your-own-key AI to draft alt text you then review and edit — every suggestion carries a “Generated by AI — please review for accuracy” note, because the model guesses and you decide.

See how it works for the full scan-and-fix flow.

The honest takeaway

Good alt text is a writing task, not a checkbox. A scanner can find the gaps and a draft can save you keystrokes, but only you know what each image is for. Write for the reader who can’t see it, mark the decorative ones empty, and treat any tool’s output — ours included — as a starting point to review, never a finished answer.