Alternative Text for CSS Generated Content

Relying on images that come from CSS has always been risky from an accessibility perspective. CSS background images, in particular, must either be purely decorative or be described to the user in some way.

The risk is no different for images coming from CSS generated content using content: url(foo.gif) (typically paired with ::before and ::after). Addressing it is often a bit trickier.

A long time ago using CSS generated content was a WCAG auto-fail. Today using content: to insert plain text can be a boon for users — from browsers using it to present quote marks for rendering <q> to authors relying on it for hints.

Too often, however, I see developers relying on images in the generated content to convey important information to users. The following construct is not uncommon:

label.required::before {
 content: url(star.png);
}

For this to convey to a user that the field is required, the image has to load and the user has to be able to see it. If either is not the case, this can be a problem.

The Future

CSS Generated Content Module Level 3 (Editor’s Draft) allows an author to specify alternative text for images (referenced through url()) or other non-text content (glyphs). Section 1.2. Alternative Text for Accessibility offers two examples, both of which involve following the non-text content with / "text".

Using plain text with an image:

.new::before {
 content: url(./img/star.png) / "New!";
  /* or a localized attribute from the DOM: attr("data-alt") */
}

Using a blank value with a strictly decorative glyph:

.expandable::before {
 content: "\25BA" / "";
 /* a.k.a. ► */
 /* aria-expanded="false" already in DOM,
   so this pseudo-element is decorative */
}

Unfortunately support is not where we need it today to rely on it. Further, for a browser that does not support the / "text" syntax, using it will invalidate the entire declaration, preventing your image or glyph from appearing. This could be some de facto progressive enhancement (if considered carefully) or you could just repeat your code without the text alternative.

Test

I wanted to compare the current state of CSS generated content alternative text with the trusty <img alt=> construct. Granted, authors both forget and write terrible alt text all the time, so we can expect the same with CSS. But it is a good idea to get a baseline understanding.

I am using it as plain text, as a heading, and as the accessible name for each of a link, a field, and a button. I also tried it with an emoji as the text alternative to maybe head that chaos off early.

If the embed does not work, visit the pen directly or try it in debug mode for your own testing.

See the Pen JjKoeGG by Adrian Roselli (@aardrian) on CodePen.

Updated Test (10 December 2021)

Following a conversation on Twitter, I updated the text to include Apple’s proprietary alt CSS property using a fallback method. The tests below have been updated to reflect current support at the time of this writing.

Results

Results as of 20 December 2024.

• Windows 11
  • Chrome 131
    • CSS: Handles images and their alternative text from CSS generated content just fine, whether or not the image renders.
    • CSS with attr(): Handles the alternative text just fine.
    • Ignores proprietary Apple CSS property (alt); handles rest of CSS as above.
    • <img>: Shows the broken image icon and its alt, without reserving space for the missing image.
    • Font symbol: Announces the alternative whether from text or attr().
  • Firefox 133
    • CSS: Handles images and their alternative text from CSS generated content just fine, whether or not the image renders.
    • CSS with attr(): Handles the alternative text just fine.
    • Ignores proprietary Apple CSS property (alt); handles rest of CSS as above.
    • <img>: Does not show a broken image icon, but does show its alt.
    • Font symbol: Announces the alternative whether from text or attr().
• macOS 15.2
  • Safari 18.2
    • CSS: Handles images fine, but does not announce the alternative text except on field and button unless you navigate by the element type or use read-all VO+A, which results in VO announcing them as two items and announcing each twice on text nodes. Shows the alternative visually only when VoiceOver is activated and then resizes the broken image to a square much larger than it was.
    • CSS with attr(): Handles the alternative text just fine, but does not announce the alternative text except on field and button unless you navigate by the element type. I did not test this with broken references, but the prior bullet likely applies.
    • Ignores proprietary Apple CSS property (alt); handles rest of CSS as above
    • <img>: Does not show the alt and may not show the broken image icon if the text height is too small (unlike how it forces a resize as noted above); announces the image alternative regardless of navigation method.
    • Font symbol: Announces the alternative whether from text or attr() when on the button, but not in a text node unless using read-all (VO+A).
• Android 15
  • Chrome 131
    • CSS: Handles images and their alternative text from CSS generated content just fine, whether or not the image renders.
    • CSS with attr(): Handles the alternative text just fine.
    • Ignores proprietary Apple CSS property (alt); handles rest of CSS as above.
    • <img>: Shows the broken image icon and its alt, without reserving space for the missing image.
    • Font symbol: Announces the alternative whether from text or attr().
  • Firefox 133
    • CSS: Handles images and their alternative text from CSS generated content just fine, whether or not the image renders.
    • CSS with attr(): Handles the alternative text just fine.
    • Ignores proprietary Apple CSS property (alt); handles rest of CSS as above.
    • <img>: Does not show a broken image icon, but does show its alt.
    • Font symbol: Announces the alternative whether from text or attr().
• iPadOS 18.2
  • Safari
    • CSS: Handles images fine. Shows the alternative visually only when VoiceOver is activated and then resizes the broken image to a square much larger than it was. Did not announce emoji alternative on a broken reference.
    • CSS with attr(): Handles the alternative text just fines.
    • Ignores proprietary Apple CSS property (alt); handles rest of CSS as above
    • <img>: Does not show the alt and may not show the broken image icon if the text height is too small (unlike how it forces a resize as noted above); announces the image alternative regardless of navigation method.
    • Font symbol: Announces the alternative whether from text or attr().

Takeaways

If you want to find a solution that works for each major platform, then do not use the CSS approach yet. Stick with images.

If you don’t care about iOS users, then Chrome is the only cross-platform browser that will work today, though that includes Chromium-based browsers (Edge, Opera, Brave, etc).

In supporting browsers, if your CSS generated content image does not load, its alternative text will not display. With the <img> element there is a good chance the alt will display.

CSS generated content will not localize easily. In the future, attr("data-alt") can potentially get around that unless you rely on automated translation tools. If you need your content to auto-translate, then the CSS approach is not for you.

No matter which of the two techniques you end up targeting for your users, avoid emoji as your alternative text.

Revised Takeaway (10 December 2021)

Even using Apple’s proprietary property with a fallback, with Apple’s quirky support in macOS 12 / Safari 15, Firefox’s complete lack of any support, Blink/Chromium’s other quirks, and TalkBack’s refusal to announce emoji in general, I reiterate my opening recommendation – stick with images.

Update: 25 April 2024

Chrome honors the alt text in images from CSS generated content and lets it contribute to the accName. If the image reference is broken, while the alternative text still contributes to the accName, the text does not display visually. Which means immediate 2.5.3 Label in Name failure.

Firefox still doesn’t support alternative text for CSS generated content.

Safari also honors the alt text in images from CSS generated content and lets it contribute to the accName. If the image reference is broken, while the alternative text still contributes to the accName, the text does not consistently display visually. The user may need to perform some trickery, like launching (or closing) VoiceOver. Doing so makes Safari’s <img alt> logic kick in (I am guessing here). That logic is problematic because it hides the alternative text completely if it is longer than the placeholder image or if the image is under 56 pixels in height.

Re-revised Takeaway

Don’t rely on alternative text on CSS generated content, especially for any kind of interactive control. Stick with HTML <img>.

Martin Underhill touched on this a bit last month in Alt text for CSS generated content.

Podcast Reference (Added 7 July 2024)

This post was mentioned in the Working Draft Podcast (or at least I think it was; I don’t speak German).

20 December 2024: Icon Fonts

The post Are icon fonts a bad practice? from the end of November makes assertions that gave me pause. Mostly that you can use alternative text for CSS generated content to provide useful content. It tested in VoiceOver alone. I immediately thought, nope, wrong.

So I updated my test case, ran it again, and it turns out, yup, that post it right. While I knew browsers have been getting updates to better support alternative text in CSS generated content, I was unaware that they were mostly in good shape. VoiceOver and Safari quirks aside, of course.

Anyway, most recent test results are above. I hid the prior test results because wow was that noisy.

Re-re-revised Takeaway

You should prefer using <img> for icons and the like, but for non-interactive decorative contexts that don’t need auto-translation, then alternative text on CSS generated content can get the job done. Even if Safari does some interesting things with it.

20 April 2025

Kevin Powell referenced this post in his video about new CSS features for 2025. If you came here from that video, scroll up just a tiny bit to see my Re-re-revised Takeaway. To recap, it’s fine to use for non-interactive decorative contexts that don’t need auto-translation.