How to Write Alt Text: Rules, Examples & Audit

How to write alt text starts with the image’s purpose. Write a short replacement for informative images, use empty alt text for decorative images, describe the action for functional images, and summarize the key takeaway for complex images. Good alt text helps screen readers and gives search engines clearer image context.

If you only remember one rule, remember this: alt text is a substitute, not a caption. It should convey what a person misses if the image does not load or cannot be seen.

Google says to write descriptive, useful alt text and avoid keyword stuffing in its image guidance at Google Search Central. The HTML standard also defines alt as replacement text for images in the WHATWG HTML spec for images.

How to write alt text: a decision tree#

Use this workflow every time.

1. Is the image purely decorative?
2. If yes, use alt="" and do not describe it.
3. If no, is the image functional, such as a button or linked image?
4. If yes, describe the action or destination.
5. If no, is the image informative?
6. If yes, describe the essential content in context.
7. If no, is it complex, such as a chart or infographic?
8. If yes, write a short alt summary and provide the full explanation nearby.

This is the part most guides skip. They list tips, but they do not give you a repeatable decision path that writers, developers, and reviewers can use.

What alt text is and why it matters#

Alt text lives in the HTML alt attribute on an img tag. Screen readers announce it as a text alternative, and search engines use it as one signal to understand image content and page context.

That means alt text serves two jobs at once. It supports accessibility first, and it can support SEO when it accurately describes the image in the page’s context.

WCAG 2.1 requires text alternatives for non-text content in many cases, with different handling depending on purpose, in the W3C Understanding WCAG 2.1 guidance. If you are auditing technical issues beyond images, YepAPI's On-Page Instant API is the fastest way to inspect on-page elements at scale.

Pass or fail checks before you publish#

Use these checks to review any alt attribute.

A strong review process catches more than missing alt text. It also catches weak alt text that is present but useless.

Alt text examples by image purpose#

Informative images#

Informative images communicate content. Describe the specific point the reader needs.

• Good: alt="Red ceramic mug on a wooden desk beside a closed notebook"
• Bad: alt="image"
• Bad: alt="coffee mug desk notebook buy mugs online best mug"

The good version names what matters. The bad versions are vague or stuffed.

Decorative images#

Decorative images add mood or spacing but no meaning. Use empty alt text.

• Good: alt=""
• Bad: alt="Blue swoosh divider across the page"

Do not skip the attribute by default. For decorative images, an empty alt tells assistive tech to ignore the image. That is different from missing alt text.

Functional images#

Functional images trigger an action or navigate somewhere. Describe the result, not the appearance.

• Good: alt="Search"
• Good: alt="Download pricing guide"
• Bad: alt="Magnifying glass icon"

If a linked image goes to the homepage, alt="YepAPI home" is stronger than alt="company logo" because it tells the user what the control does.

Complex images#

Complex images include charts, diagrams, maps, and infographics. Keep the alt short, then provide a fuller explanation in nearby text.

• Good alt: alt="Bar chart showing organic traffic rising from January to June, with June highest"
• Better support nearby: one or two sentences below the image explaining the exact values or takeaway
• Bad: alt="chart"

When you need to verify these patterns across templates and URLs, YepAPI's On-Page Content API helps you extract image-adjacent text for quality checks, not just presence checks.

alt text examples for edge cases teams actually ship#

alt text for buttons#

Buttons need action-focused alt text when the image itself is the control.

If the button already has visible text, the image inside it is often decorative.

  Search

This is one of the easiest ways to avoid duplicate announcements from screen readers.

alt text for logos#

Logo alt text depends on context.

1. If the logo is the only brand identifier in a header, use the brand name.
2. If the logo links home, use the destination or function, such as YepAPI home.
3. If the logo appears again in a partner grid with nearby brand text, it may be redundant.

Examples:

• Good: alt="YepAPI"
• Good: alt="YepAPI home"
• Bad: alt="Blue unicorn startup API platform logo image"

alt text for infographics#

Infographics are complex images. Alt text should summarize the core takeaway, not transcribe every label.

• Good: alt="Infographic showing a four-step alt text workflow: decorative, functional, informative, or complex"
• Bad: alt="Infographic with boxes, arrows, icons, and text"

Then add the full explanation in body copy below the image. If you want to check whether pages include that supporting explanation, YepAPI's Web Scraping Extract API is useful for pulling repeated content patterns from rendered pages.

Repeated UI icons#

A repeated icon in a list or nav often does not need descriptive alt text if nearby text already names the item. Use empty alt text when the icon adds no standalone meaning.

Images of text#

If an image contains text that matters, the alt should include that text or its equivalent meaning. If the text is already present as real text right beside the image, avoid repeating it unless the image needs its own replacement.

Code patterns developers can ship#

Here are the patterns most teams actually need.

Standard informative image#

Decorative image#

Linked image#

Logo linking home#

[](/)

Chart with nearby description#

Traffic rose each week, from 2,100 sessions in week one to 4,900 in week eight.

If you are working through broader page quality issues, this fits naturally into a how to do on page seo workflow and a larger set of technical seo best practices.

Common mistakes that make alt text worse#

1. Starting with "image of" or "picture of" when the context already makes that obvious.
2. Stuffing keywords into every image.
3. Describing decorative images that should be ignored.
4. Writing generic text like photo, graphic, or logo.
5. Repeating nearby captions word for word.
6. Forgetting that buttons and linked images need action-based text.
7. Omitting the longer explanation for charts and infographics.

A useful rule is simple: if the alt does not help someone understand the page better, rewrite it or empty it.

How to test alt text after you write it#

Test alt text in three passes.

1. Read the page with images mentally removed. Would the alt preserve the meaning?
2. Navigate key pages with a screen reader and listen for redundancy, noise, or missing purpose.
3. Run an automated crawl to find missing, empty, duplicate, and suspiciously long alt text.

Automated checks catch scale problems. Manual testing catches quality problems.

For technical QA, browser and accessibility tooling will expose missing or weak image alternatives, and many teams also pair that with broader markup checks like structured data in guides such as how to create rich snippets. If the page itself breaks or returns the wrong status, fix that first; even perfect alt text does not help a page with a crawl issue like the one explained in http 404 error meaning.

Programmatic alt text auditing across a site#

This is where most alt text articles stop, but developers and SEOs need a repeatable audit method.

Audit for these patterns across every important URL:

1. Missing alt attribute
2. Empty alt on non-decorative images
3. Duplicate alt text reused across unrelated images
4. Overlong alt text that reads like copy, not replacement text
5. Filename leakage such as hero-final-2.jpg
6. Keyword-stuffed alt text
7. Linked images with appearance-based text instead of action-based text

YepAPI's On-Page Instant API is the quickest way to inspect page elements in code across many URLs. Pair it with YepAPI's Web Scraping API when you need the rendered HTML from JavaScript-heavy pages, or YepAPI's On-Page Lighthouse API when alt text review is part of a wider technical accessibility pass.

A practical workflow looks like this:

1. Export a list of URLs from your CMS, sitemap, or crawl.
2. Request each page and extract image markup.
3. Classify each image as decorative, functional, informative, or complex.
4. Flag missing, empty, duplicate, and overlong values.
5. Review high-traffic and template-driven pages first.
6. Re-test after deployment.

If you also monitor domain-level quality signals, that work often sits beside broader audits like how to check website domain authority, but alt text quality is a page-level implementation problem first.

alt text generator: when to use one and when not to#

An alt text generator can speed up drafting. It should not be the final reviewer.

Generators are most useful for producing a first pass on large image libraries. They are least reliable when page context matters, such as product comparison charts, navigation icons, logos, and screenshots with task-specific meaning.

Treat generated output as suggested copy. Your editor or QA step still needs to check purpose, context, redundancy, and action.

A simple workflow for teams#

If you need a process that survives handoffs between content, design, and engineering, use this one.

1. Writer identifies the image purpose.
2. Designer marks decorative assets clearly.
3. Developer implements the correct alt pattern.
4. Reviewer checks against the pass/fail table.
5. SEO or engineering runs a sitewide audit.
6. Team re-tests priority templates after release.

This keeps alt text from becoming a last-minute field that someone fills with filenames or keywords.

Use YepAPI's Keyword API? No — use the page and audit APIs here#

This topic is not really about keyword research. It is about implementation quality and repeatable checks.

That is why YepAPI's On-Page Instant API is the right product fit here. You can inspect pages in code, catch image-alt problems at scale, and fold them into the same remediation queue as redirects, robots directives, and other issues covered in what is robots txt and 301 redirect vs 302.

CTA#

Need to audit image alt text across hundreds or thousands of pages? Pull page elements with YepAPI's On-Page Instant API and automate checks for missing, empty, duplicate, and weak alt text. $5 free credit, no card.

FAQ#

What is considered alt text?#

Alt text is the value of an image’s alt attribute in HTML. It acts as a text replacement for the image when the image cannot be seen or loaded. Good alt text reflects the image’s purpose on the page, not just what the pixels look like in isolation.

How to write text for blind people?#

Write for the information they need, not for a sighted description exercise. Replace the image with the shortest text that preserves meaning, function, or outcome. Use empty alt text for decorative images, action-focused text for controls, and a brief summary plus nearby detail for charts or infographics.

What are the best practices for alt text in 2026?#

The best practices are still purpose-based. Match the alt text to whether the image is decorative, functional, informative, or complex. Keep it concise, avoid keyword stuffing, do not repeat nearby captions without reason, and test important templates with both automated checks and a screen reader.

How do I add alt text to images in Canvas?#

In most Canvas editors, select the image and look for image options or accessibility settings, then enter a short text alternative or mark the image as decorative if it adds no meaning. After saving, test the page in student view and confirm the image purpose is still clear without seeing it.