Yoast's image keyphrase check: alt text for people first
Yoast SEO's Keyphrase in image alt attributes check reads the alt text of the images in your post and looks for your focus keyphrase or a synonym. With fewer than five images, one matching alt attribute turns it green. With five or more, Yoast wants between 30 and 75 percent of them to match, and it warns you if more than that do.
Alt text exists so people who cannot see an image still get its meaning. Search engines use it too, mainly for image search, but a keyword that does not describe the picture helps nobody. Write the description first, and let the keyphrase in only where it is true.
The scoring, image count by image count
Yoast counts an alt attribute as matching when it contains at least half of the content words in your keyphrase, or a synonym. The rest depends on how many images the post has:
| Situation | Result |
|---|---|
| No images, or no keyphrase set | Red |
| Images, but none have alt text | Orange (red for cornerstone content) |
| Alt text present, but none reflect the keyphrase | Orange (red for cornerstone content) |
| Fewer than 5 images, at least one match | Green |
| 5 or more images, 30% to 75% match | Green |
| 5 or more images, under 30% or over 75% match | Orange |
The over-75 percent message is worth reading literally: "That's a bit much. Only include the keyphrase when it really fits the image." Yoast built in the cap to stop the check from rewarding alt text that repeats the keyword on every photo. The check does not run on category and tag archives.
Two jobs for one attribute
The alt attribute was added to HTML so that screen readers could speak a description of an image, and so browsers had something to show when an image failed to load. That is still its main job.
The search use came later. Search engines cannot always tell what an image shows, so the alt text is one of the clearest hints they have, alongside the file name, the caption and the text around the image. Google's image guidance asks for descriptive, useful alt text and warns against filling it with keywords.
The tension is obvious: a check that asks for keywords in alt text can pull writers toward describing the keyword instead of the picture. The honest way through is to describe what the image shows in context. When the image really is of the thing your page is about, the keyphrase appears on its own.
Ranking impact, in proportion
For image search, alt text matters a lot: it is often how an image gets matched to a query in the first place. For the page's normal web ranking, the effect is small. A post will not climb because three alt attributes repeat its keyword, and it will not drop because a diagram's alt text describes the diagram instead.
So fix this check when your images have no alt text at all, which is an accessibility gap and a lost image search opportunity. Be relaxed about it when your images are well described but simply show related things, such as the tools used in a tutorial rather than the finished result.
Writing alt text that passes honestly
Take a post with the keyphrase lemon drizzle cake and six photos:
- Finished cake: "Lemon drizzle cake on a wire rack, glaze still wet." (matches)
- Ingredients: "Lemons, caster sugar, butter and eggs laid out on a counter."
- Mixing: "Creaming butter and sugar in a stand mixer."
- Glazing: "Spooning lemon syrup over the warm drizzle cake." (matches)
- Slice: "A slice of lemon cake showing the moist crumb." (matches, since lemon and cake are two of three content words)
- Serving: "Tea and cake served on a garden table."
The serving photo does not match: cake alone is one of three content words, which is less than half. Three of six images match, 50 percent, which is green. Nothing had to be stuffed.
Two rules keep you out of trouble. Purely decorative images, such as dividers, should have empty alt text (alt="") so screen readers skip them, even if that lowers the count. And never write "image of" or "picture of"; assistive technology already announces that it is an image.
Alt text in Hydrogen SEO
Hydrogen SEO scores alt text differently. Image alt text is one fifth of its SEO score: full points when every image in the content has alt text, half when some do, and zero when none do or the post has no images. It checks that alt text exists, not whether it contains the keyword.
For writing it, the Media Library has a Generate Alt Text button for one image or a bulk selection, at one credit per image with a free connected account, and a free Add Missing ALT Attributes fallback that fills empty alt attributes from a template. That fallback also fills intentionally empty decorative alt text, so read the caveats in image alt text first.
Common questions
Does Yoast read the image title or caption for this check?
No. It reads the alt attribute. Captions and title attributes are separate, although captions do help readers and give search engines extra context.
Why is the check orange when I have many images with keyword alt text?
With five or more images, Yoast wants between 30 and 75 percent to reflect the keyphrase. Above 75 percent it asks you to only use the keyphrase when it really fits the image.
Should decorative images get keyword alt text to pass the check?
No. Decorative images should have empty alt text so screen readers skip them. Passing a plugin check is not worth making the page worse for people using assistive technology.