How to Write Alt Text: A Practical Guide for Developers and Content Teams

Missing or inadequate alt text remains the second most common accessibility failure on the web, affecting over half of all homepages. This guide cuts through the vague advice and gives developers, designers, and content teams concrete rules, code examples, and decision frameworks for writing alt text that actually serves users — and keeps sites legally compliant.

According to the WebAIM Million 2025 report, missing alternative text affects 55.5% of all homepages analyzed — and of those failures, 44% involve linked images, which completely breaks navigation for screen reader users. That's not a niche problem. That's half the web leaving blind and low-vision users stranded in front of images that say nothing. If your team ships images without thinking carefully about alt text, you're not just failing a compliance checkbox — you're telling a significant portion of your audience that their experience doesn't matter. <h2>What Alt Text Actually Is (and Why It's More Than a Tag)</h2> Alt text, short for alternative text, is a written description embedded in the <code>alt</code> attribute of an HTML <code><img></code> element. When a screen reader encounters an image, it reads the alt text aloud to the user. When an image fails to load — due to a slow connection, a broken URL, or a content blocker — the alt text renders in its place. It's also indexed by search engines, making it a quiet but meaningful SEO signal. But here's what many teams miss: alt text isn't just a fallback safety net. It's the primary way that blind and low-vision users — roughly 43.3 million people worldwide who are blind, and 295 million with moderate to severe low vision — experience visual content on the web. Screen readers like NVDA and JAWS (the two most widely used desktop screen readers) announce alt text the moment focus reaches an image. If that text is absent, meaningless, or redundant, the user experience degrades immediately. Research on blind and low-vision users paints a stark picture of what happens in practice. Some users report ignoring images on websites entirely because, in their experience, the alt text is never useful. Others skip product images on e-commerce sites and rely on user reviews instead, because alt text like "image001.jpg" or "photo" tells them nothing. That's not a screen reader problem — that's a content problem, and it's one your team can fix. Understanding alt text as a content responsibility — not just a developer task — is the first mental shift every team needs to make. The developer implements the attribute; the content team understands the context. Both are essential to getting it right. <h2>The Legal and Compliance Landscape</h2> Alt text isn't optional if you care about legal exposure. WCAG Success Criterion 1.1.1 (Non-text Content) is a Level A requirement — the lowest, most foundational tier of compliance. Failing it means failing any formal accessibility audit. In the United States, the ADA has been applied to websites in thousands of cases, with 4,605 ADA website lawsuits filed in 2024 alone. Missing alt text is one of the most cited violations in demand letters precisely because it is easily detectable, objectively measurable, and directly blocks access to core content. Beyond the ADA, the European Accessibility Act (EAA) became enforceable on June 28, 2025. If your organization serves customers in the EU, non-compliance can carry penalties up to €100,000 or 4% of annual revenue. WCAG 2.2 Level AA is widely recognized as the benchmark for EAA compliance, and its alt text requirements under criterion 1.1.1 are unchanged from earlier versions — all informative images must have programmatically determinable text alternatives. In Canada, the Accessibility for Ontarians with Disabilities Act (AODA) similarly mandates WCAG conformance for public and private sector organizations. Section 508 in the US federal context has its own parallel requirements. The takeaway is consistent across jurisdictions: alt text is not a nice-to-have, and the regulatory environment is tightening, not loosening. <blockquote>WCAG 1.1.1 is Level A — the most basic compliance tier. Failing it means failing every accessibility audit, and it's the easiest violation for automated tools and legal teams to detect.</blockquote> <h2>The Decision Framework: Which Images Need What</h2> One of the most common misconceptions is that every image needs a text description. That's incorrect — and adding unnecessary alt text to decorative images actually makes the experience worse for screen reader users, who then have to listen to noise that adds no value. The real skill is knowing which category each image falls into. Here's a practical framework: <ul> <li>Informative images — Photos, illustrations, or graphics that convey content or meaning not present in surrounding text. These require descriptive alt text that communicates the same information the image provides.</li> <li>Functional images — Images used as buttons, links, or controls (e.g., a magnifying glass icon that submits a search, or a logo that links to the homepage). Alt text should describe the function, not the visual appearance: <code>alt='Search'</code>, not <code>alt='Magnifying glass icon'</code>.</li> <li>Decorative images — Visual flourishes that add aesthetic value but carry no meaning: background patterns, dividers, purely decorative illustrations. These should have an empty alt attribute (<code>alt=''</code>), which tells the screen reader to skip the image entirely.</li> <li>Images of text — Screenshots or graphics that contain words. Best practice is to avoid these altogether and use real, styled text instead. When they're unavoidable, the alt text should reproduce the text in the image verbatim.</li> <li>Complex images — Charts, graphs, maps, and infographics that contain dense data. A short alt text summary is required, plus a longer structured description in the page body or linked from the image.</li> </ul> Note that empty alt text (<code>alt=''</code>) is not the same as a missing alt attribute. An image with no <code>alt</code> attribute at all may cause the screen reader to read the image filename or URL aloud — which is almost always worse than silence. Always include the attribute, even when its value is intentionally empty. <h2>Writing Alt Text That Actually Works: Practical Rules</h2> Good alt text is harder to write than it looks. Here are the concrete rules that separate useful descriptions from noise: <ul> <li>Keep it concise. Aim for under 125 characters. Screen readers like JAWS and NVDA may truncate longer alt text mid-sentence, cutting off exactly the information you worked hard to provide. If the image is complex enough to require more, that's a signal you need a supplementary long description.</li> <li>Don't start with "Image of" or "Photo of." Screen readers automatically announce that an element is an image before reading the alt text. Writing <code>alt='Image of a smiling woman'</code> causes the screen reader to say "image, image of a smiling woman" — which is redundant and wastes the listener's time.</li> <li>Describe the meaning, not just the appearance. Alt text should communicate the same information or function as the image. If you're showing a chart of Q3 revenue growth, don't write <code>alt='Bar chart'</code>. Write something like <code>alt='Bar chart showing Q3 revenue up 22% year-over-year'</code>, then provide the full data in surrounding text.</li> <li>Match the context. The same photograph can require different alt text depending on where it's used. A photo of a laptop on a desk used in a "Meet Our Team" section might need alt text describing the workspace; used in a product listing, it needs to describe the laptop's specifications and appearance.</li> <li>Don't stuff keywords. Alt text is indexed by search engines, but keyword-stuffing it is both a poor user experience and a violation of WCAG's intent. Write for the user first.</li> <li>Use proper grammar and punctuation. Screen readers translate text to speech, and punctuation affects pacing and clarity. A sentence fragment reads less naturally than a complete thought.</li> </ul> <blockquote>Alt text doesn't need to be a cold, objective description. It can — and sometimes should — convey nuance, context, and even emotion when those qualities are relevant to the user's experience of the content.</blockquote> <h2>Code Examples: Right and Wrong</h2> Theory is one thing. Let's look at how these principles play out in actual HTML. Informative image — poor alt text: <pre><code><img src='team-photo.jpg' alt='photo'></code></pre> Informative image — good alt text: <pre><code><img src='team-photo.jpg' alt='Accsible engineering team gathered around a whiteboard during a product sprint meeting'></code></pre> Functional image (linked logo) — poor alt text: <pre><code><a href='/'> <img src='logo.svg' alt='logo'> </a></code></pre> Functional image (linked logo) — good alt text: <pre><code><a href='/'> <img src='logo.svg' alt='Accsible — return to homepage'> </a></code></pre> Decorative image — correct implementation: <pre><code><img src='decorative-wave-divider.svg' alt='' role='presentation'></code></pre> Complex image (chart) — correct approach with linked long description: <pre><code><img src='q3-revenue-chart.png' alt='Bar chart: Q3 revenue up 22% YoY. Full data table below.' aria-describedby='chart-description' > <div id='chart-description'>  </div></code></pre> For icon buttons that have no visible text label, use <code>aria-label</code> on the button itself and set <code>alt=''</code> on the icon image to avoid double-announcing: <pre><code><button aria-label='Close dialog'> <img src='close-icon.svg' alt=''> </button></code></pre> <h2>Handling Specific Image Types</h2> Product images in e-commerce: These are among the most critical alt text contexts on the web. Blind users rely entirely on alt text to understand what they're considering purchasing. Describing only the product name is insufficient. Include material, color, key visual features, and any variants that are visually distinguishable. For example: <code>alt='Slim-fit wool blazer in navy blue with gold buttons and notched lapels'</code> is far more useful than <code>alt='Blazer'</code>. Logos: Logos are never decorative. They require alt text that includes the organization name and any meaningful tagline or descriptor that appears within the logo image. If the logo is also a link, the alt text should describe its destination, as discussed above. Infographics: These are notoriously difficult to handle well. A single alt attribute cannot carry the informational weight of a complex infographic. The right approach is a short, summary-level alt text (e.g., <code>alt='Infographic summarizing five steps of our onboarding process'</code>) paired with a structured text version of the same information visible on the page. Images of people: Including names when people are identified is helpful, especially in editorial or news contexts. Describe what the person is doing or what the image communicates, not just their physical appearance. Avoid descriptions that reduce a person to their demographic characteristics. Background and CSS images: Images applied via CSS <code>background-image</code> have no <code>alt</code> attribute available, so they should be used only for genuinely decorative purposes. If an image needs to communicate meaning, it belongs in the HTML as an <code><img></code> element with proper alt text. <h2>Building Alt Text Into Your Workflow</h2> One of the reasons alt text stays broken at scale is that it's treated as a final-step afterthought — something an automated scanner flags post-launch, prompting a hasty patch. The fix is to move alt text upstream into your content and development workflows. For content teams, this means establishing a house style guide for alt text that covers your most common image types. If your site publishes product images, blog post hero images, event photos, and data charts, each category deserves a documented standard with examples of good and poor descriptions. When writers and editors upload images, they should be thinking about alt text at the same moment they're thinking about captions and image selection. For developers, this means building alt text fields into CMS templates and marking them as required — not optional — for non-decorative image components. When a component accepts an image, the interface should prompt for alt text and distinguish between informative and decorative contexts. Avoid autofilling the alt attribute with the image filename or the caption text, which are different things serving different purposes. For QA and compliance managers, automated scanning tools (including accessibility overlay solutions like Accsible) can catch images with missing or empty alt attributes at scale, flagging them in real time. But automated tools cannot evaluate whether the alt text that exists is actually meaningful — that judgment requires a human reviewer. Build manual spot-checks into your accessibility auditing cadence, and include alt text quality review in any new feature acceptance criteria that involves images. When the same image is reused across multiple pages or contexts, remember that the appropriate alt text may change. A photo of a company headquarters used on a "Contact Us" page and on an "About Our Culture" page may warrant different descriptions depending on what each page is trying to communicate. CMS platforms like WordPress allow post-level alt text overrides for exactly this reason. <h2>Common Mistakes to Avoid</h2> Even teams that take alt text seriously make recurring mistakes. Here are the patterns worth actively watching for: <ul> <li>Using the filename as alt text. An alt text of <code>IMG_4521.jpg</code> or <code>hero-banner-v3-final.png</code> is worse than useless — it actively signals to screen reader users that no one thought about them.</li> <li>Making alt text identical to the adjacent caption. Captions and alt text serve different audiences and different purposes. A caption is supplementary context for sighted users; alt text replaces the image for users who can't see it. They can overlap, but shouldn't be copy-pasted interchangeably.</li> <li>Adding alt text to every image indiscriminately. Giving decorative images descriptive alt text forces screen reader users to wade through irrelevant content. The discipline of deciding "does this image need a description, and if so, what kind?" is as important as the writing itself.</li> <li>Writing vague, context-free descriptions. Alt text like <code>alt='man smiling'</code> for a photo of your CEO during a product launch tells the user almost nothing about why the image is there or what it means in context.</li> <li>Ignoring alt text on SVGs. Inline SVGs need accessible names too, typically via <code>aria-label</code> on the <code><svg></code> element or a <code><title></code> element as the first child, combined with <code>role='img'</code>.</li> </ul> <pre><code> <svg role='img' aria-labelledby='svg-title'> <title id='svg-title'>Quarterly revenue growth, Q1 to Q4 2024</title>  </svg></code></pre> <h2>Key Takeaways</h2> <ul> <li>Not every image needs a text description. Decorative images should use <code>alt=''</code> to tell screen readers to skip them — but never omit the <code>alt</code> attribute entirely, or the screen reader may announce the filename instead.</li> <li>Keep alt text under 125 characters for informative images; screen readers may cut off longer strings, and conciseness improves listening comprehension. For complex images, pair a short alt summary with a full text description in the page body.</li> <li>Describe function, not just form. For linked and functional images, alt text should tell the user what will happen or where they'll go — not what the image looks like. For informative images, communicate the meaning, not just the visual content.</li> <li>Build alt text into your workflow upstream, not as a post-launch fix. Make it a required field in your CMS, include it in content style guides, and add quality review to your QA process — automated tools catch missing alt text, but humans must evaluate whether it's meaningful.</li> <li>The legal and regulatory stakes are real and rising. ADA litigation citing missing alt text numbered in the thousands in 2024, and the EU's Accessibility Act is now in force. Treating alt text as an afterthought is not a viable compliance strategy.</li> </ul>

Alt textWcagImagesGuideAccessibilityScreen readersComplianceHtml