Alt text for code images: how to make code screenshots accessible

Quick answer: For an image of code, the most useful alt text is a short description of what the code does followed by the code itself, as text. Don't describe the theme, colors or window decoration. If readers need to copy or run the code, provide a real text code block instead of — or alongside — the image.

An image of code looks great and communicates quickly — for sighted readers on a good connection. For everyone else it can be a dead end. Screen readers cannot read the pixels, search engines index only the surrounding text, translation tools skip it, and nobody can copy from it.

None of that means you should stop using code images. It means you should use them deliberately and always pair them with text. This guide shows how.

Who is affected when code is only an image

• Blind and low-vision developers using screen readers or magnification.
• People on slow or metered connections whose images do not load.
• Readers using translation tools, which do not translate text inside images.
• Anyone who wants to copy the code, which is most readers of a tutorial.
• Search engines, which understand an image's content mainly from its alt text and the surrounding text.

Image or code block? A simple decision rule

Ask what the reader will do with the code.

The reader will…	Use
Copy, run or adapt it	A text code block
Look at it to understand an idea	An image (with alt text)
Both	An image followed by a code block, or an image with a link to the source

Installation commands, configuration snippets and tutorial steps belong in text. Comparisons, before-and-after changes, highlights of new syntax, slides and social posts are where images shine. On social platforms you cannot embed a code block, so the image is often the only option — which is exactly where good alt text matters most.

How to write alt text for code

Alt text replaces the image for anyone who cannot see it. For a photo you describe what is shown. For code, the most useful description is usually the code itself, introduced by a short note about what it is.

A template that works:

[Language] code that [does what]:
[the code, as text]

For example:

JavaScript code using optional chaining and nullish coalescing:
const city = user?.address?.city ?? "Unknown";

Guidelines

• Include the code verbatim when it fits. X allows 1,000 characters of alt text and Mastodon allows 1,500 — enough for most snippets you would put in an image.
• Summarize when it does not fit. Describe the structure and quote the important lines: "A 30-line Express server. The key line adds rate limiting: app.use(rateLimit({ windowMs: 60000, max: 100 }))."
• Describe emphasis that carries meaning: "Line 4 is highlighted," or "The removed line is if (x == null); the added line is if (x === null)."
• Skip decoration. The theme name, gradient background and window buttons do not help anyone.
• Do not start with "Image of" or "Screenshot of." Screen readers already announce that it is an image.
• Put the takeaway in the caption or post, and the code in the alt text, so each does its own job.

Alt text for terminal screenshots

For terminal images, list the commands and the output that matters:

Terminal session installing and starting the app:
$ npm install
$ npm run dev
Output: Ready on http://localhost:3000

Alt text for diffs

For a diff, say which lines were removed and added, rather than relying on color:

Diff of src/cart.ts. Removed: sum += item.price;
Added: sum += item.price * item.quantity;

When alt text should be empty

On your own website, if the exact same code appears as text right next to the image — say, a decorative hero image above the real code block — use an empty alt="" so screen readers skip the duplicate instead of reading the code twice.

Make code images readable: contrast and color

The Web Content Accessibility Guidelines (WCAG) recommend a contrast ratio of at least 4.5:1 for normal text and 3:1 for large text. Many popular syntax themes deliberately give comments, punctuation and parameters low contrast, to push them into the background.

That is fine in an editor, where you can lean in. In an image that will be scaled down, it is risky.

• If a comment carries your message, choose a theme with brighter comments, or put the message in the caption.
• Never rely on color alone. Around 1 in 12 men and 1 in 200 women have some form of color-vision deficiency, and red–green is the most common. Diff markers (+ and -), labels and annotations keep the meaning without color.
• Test the result, not the theme name. Both light themes (such as GitHub Light) and dark themes (such as One Dark) can be accessible; check the tokens that matter in your snippet.
• Keep the font large. Crisp text at 2× resolution helps low-vision readers as much as anyone.

Free tools such as the WebAIM contrast checker tell you whether a pair of colors meets the guideline.

Accessible code images in documentation and blogs

On your own site you control the HTML, so you can do better than alt text alone:

• Wrap the image in a <figure> with a <figcaption> explaining the takeaway.
• Follow the image with a real code block, or a clearly labeled "View source" link.
• Use SVG for images that sit on your page, so they stay sharp when readers zoom. See PNG vs SVG for code images.
• Make sure the page still makes sense if the image never loads.

Accessible code in slides and talks

In a talk, the people at the back of the room are your low-vision readers. Use the largest font the slide can hold, show fewer lines, and read the important line aloud. When you publish the slides, add alt text or speaker notes containing the code, and link to the repository.

An accessibility checklist for code images

1. Would readers need to copy this? If so, there is a text version.
2. The alt text contains the code, or a faithful summary, and says what it does.
3. Meaning never depends on color alone.
4. Important tokens meet contrast guidelines; comments that matter are readable.
5. Text is readable at the size people will actually see.

Codeshot's code to image generator and terminal session tool let you edit the text directly on the canvas, so the exact text you render is the text you paste into your alt text — no retyping and no mismatch. For more on making code images effective, see the code screenshot best practices.

Frequently asked questions

What should alt text for a code screenshot say?

A short description of what the code does, followed by the code itself as text. If the code is too long, summarize the structure and quote the most important lines.

Are screenshots of code bad for accessibility?

Only when they are the only way to get the code. Pair every code image with alt text that contains the code, and provide a copyable code block or a link to the source whenever readers might need to run it.

What contrast ratio should code images have?

WCAG recommends at least 4.5:1 between normal-sized text and its background, and 3:1 for large text. Check comments and punctuation especially, since many themes style them with low contrast.

How long can alt text be on social media?

X allows up to 1,000 characters and Mastodon up to 1,500, which is enough for most short code snippets. Other platforms have their own limits; when space is tight, summarize and quote the key lines.