Build an Image Alt Text Checker Extension: Complete 2025 Developer’s Guide
Web accessibility has transformed from an optional consideration into a fundamental requirement for modern web development. With over one billion people worldwide experiencing some form of disability, ensuring your websites are accessible is no longer just good practice—it is essential for reaching your entire audience. One of the most critical aspects of web accessibility is proper image alt text, yet it remains one of the most commonly overlooked elements in web development.
In this comprehensive guide, we will walk you through building a fully functional Chrome extension that checks images for proper alt text, validates accessibility compliance, and helps developers ensure their websites meet WCAG standards. Whether you are a seasoned developer or just starting with Chrome extension development, this guide provides everything you need to create a powerful accessibility tool.
Why Image Alt Text Matters for Web Accessibility
Before diving into the technical implementation, it is crucial to understand why image alt text is so important for web accessibility. Screen readers rely on alt text to describe images to visually impaired users, making it the primary way these users can understand visual content on the web. Without proper alt text, approximately 8% of websites becomes inaccessible to blind and low-vision users.
Beyond accessibility, alt text provides significant SEO benefits. Search engines cannot “see” images the way humans can; they rely on alt text, file names, and surrounding context to understand what an image depicts. Proper alt text improves your images’ search rankings and helps drive organic traffic to your website.
Many developers understand the importance of alt text but struggle with implementation. Common issues include missing alt attributes entirely, using placeholder text like “image1” or “picture,” writing descriptions that are too brief or too long, and decorative images that should use empty alt attributes. An alt text checker extension solves all these problems by automatically scanning pages and flagging issues.
Understanding Chrome Extension Architecture
Chrome extensions are built using standard web technologies: HTML, CSS, and JavaScript. They can interact with web pages through content scripts, communicate with browser APIs through background scripts, and provide user interfaces through popup pages or options pages.
For our alt text checker extension, we need three main components working together. The manifest.json file defines the extension’s configuration, permissions, and entry points. Content scripts run in the context of web pages and can analyze the DOM to find images. The popup or options page provides the user interface for displaying results and configuring the extension.
Chrome extensions follow a specific file structure. The manifest.json must be in the extension’s root directory, and all other files are referenced relative to this location. Understanding this architecture is fundamental before you begin writing code.
Setting Up the Extension Project
Create a new directory for your extension project. Inside this directory, create the following essential files: manifest.json, popup.html, popup.js, content.js, and styles.css. Each file serves a specific purpose in the extension’s functionality.
Your manifest.json file defines how Chrome loads and interacts with your extension. For an alt text checker, we need the “activeTab” permission to access the current page’s content, and the “scripting” permission to execute content scripts. The manifest also specifies which files to load and defines the extension’s browser action (the icon that appears in Chrome’s toolbar).
The content script is where the magic happens. This JavaScript file runs in the context of every web page the user visits, allowing us to analyze the DOM and find all image elements. We can then check each image’s alt attribute and determine whether it meets accessibility standards.
Building the Manifest Configuration
The manifest.json file is the heart of any Chrome extension. It tells Chrome about your extension’s capabilities, permissions, and how it should behave. For our alt text checker, we need to carefully configure several key sections.
{
"manifest_version": 3,
"name": "Alt Text Checker",
"version": "1.0",
"description": "Check images for proper alt text and accessibility compliance",
"permissions": ["activeTab", "scripting"],
"host_permissions": ["<all_urls>"],
"action": {
"default_popup": "popup.html",
"default_icon": {
"16": "icons/icon16.png",
"48": "icons/icon48.png",
"128": "icons/icon128.png"
}
},
"content_scripts": [{
"matches": ["<all_urls>"],
"js": ["content.js"]
}]
}
This manifest version 3 configuration grants the extension access to analyze any webpage while maintaining user privacy through the activeTab permission. The content_scripts section ensures our analysis script runs automatically when pages load.
Creating the Content Analysis Script
The content script is where we implement the core functionality of scanning images and checking their alt attributes. This script runs in the context of each web page, giving us access to the full DOM and all image elements.
Our analysis function needs to find every img element on the page and evaluate its alt attribute according to accessibility guidelines. There are several scenarios we must handle: images with proper alt text, images with empty alt attributes (appropriate for decorative images), images missing alt attributes entirely, and images with placeholder or inadequate alt text.
function analyzeImages() {
const images = document.querySelectorAll('img');
const results = {
total: images.length,
pass: 0,
fail: 0,
warnings: 0,
details: []
};
images.forEach((img, index) => {
const alt = img.getAttribute('alt');
const src = img.src || img.currentSrc;
const id = img.id || `img-${index}`;
let status = 'pass';
let message = '';
if (alt === null) {
status = 'fail';
message = 'Missing alt attribute entirely';
} else if (alt.trim() === '') {
status = 'pass';
message = 'Empty alt text (appropriate for decorative images)';
} else if (isPlaceholder(alt)) {
status = 'warning';
message = 'Alt text appears to be a placeholder';
} else if (alt.length < 5) {
status = 'warning';
message = 'Alt text too short to be descriptive';
} else if (alt.length > 125) {
status = 'warning';
message = 'Alt text may be too long for screen readers';
} else {
message = 'Alt text is present and appears descriptive';
}
if (status === 'pass') results.pass++;
else if (status === 'fail') results.fail++;
else results.warnings++;
results.details.push({ id, src, alt, status, message });
});
return results;
}
function isPlaceholder(text) {
const placeholders = ['image', 'picture', 'photo', 'img', 'pic', 'graphic', 'image1', 'image2', 'pic1'];
const lower = text.toLowerCase().trim();
return placeholders.includes(lower) || /^(image|picture|photo|img)\s*\d+$/i.test(lower);
}
This script provides a comprehensive analysis of all images on the page, categorizing them by their alt text quality and generating detailed reports for the user.
Implementing the Popup Interface
The popup provides the user interface for interacting with your extension. When users click the extension icon, they should see a summary of accessibility issues and have options to scan the current page or view detailed results.
Create an HTML file for your popup with sections for displaying summary statistics, a button to trigger analysis, and a detailed list of findings. Style it with CSS to match Chrome’s Material Design aesthetic for a professional appearance.
The popup JavaScript handles user interactions and communicates with the content script. When the user clicks the “Analyze” button, the popup sends a message to the active tab requesting an analysis. The content script responds with results, which the popup then displays to the user.
document.addEventListener('DOMContentLoaded', function() {
const analyzeBtn = document.getElementById('analyzeBtn');
const resultsDiv = document.getElementById('results');
analyzeBtn.addEventListener('click', function() {
chrome.tabs.query({ active: true, currentWindow: true }, function(tabs) {
chrome.tabs.sendMessage(tabs[0].id, { action: 'analyze' }, function(response) {
displayResults(response);
});
});
});
function displayResults(results) {
if (!results || results.total === 0) {
resultsDiv.innerHTML = '<p>No images found on this page.</p>';
return;
}
let html = `
<div class="summary">
<h3>Analysis Results</h3>
<p>Total Images: ${results.total}</p>
<p class="pass">Passing: ${results.pass}</p>
<p class="warning">Warnings: ${results.warnings}</p>
<p class="fail">Failing: ${results.fail}</p>
</div>
<div class="details">
<h4>Detailed Findings</h4>
`;
results.details.forEach(img => {
html += `
<div class="result-item ${img.status}">
<strong>${img.status.toUpperCase()}</strong>
<p>${img.message}</p>
<code>${truncate(img.src, 50)}</code>
</div>
`;
});
html += '</div>';
resultsDiv.innerHTML = html;
}
});
This code creates an interactive popup that communicates with your content script and displays results in an easy-to-read format.
Adding Advanced Features
While the basic implementation covers most use cases, adding advanced features makes your extension truly valuable for developers and accessibility professionals.
Consider implementing real-time scanning that automatically analyzes pages as users navigate. This feature would use Chrome’s webNavigation API to detect page loads and trigger analysis automatically. Users could enable or disable this feature through an options page.
Another powerful addition is export functionality. Users should be able to export analysis results in various formats, including CSV for spreadsheets, JSON for programmatic use, and PDF for reports. This feature is particularly valuable for accessibility audits and compliance documentation.
You might also consider adding support for additional accessibility checks beyond alt text. This could include checking for proper heading hierarchy, link text quality, color contrast ratios, and ARIA attribute usage. Building a comprehensive accessibility toolkit increases the value of your extension significantly.
Testing Your Extension
Before publishing your extension to the Chrome Web Store, thorough testing is essential. Start by loading your extension in developer mode through Chrome’s extensions page. Enable “Developer mode” in the top right corner, then click “Load unpacked” and select your extension directory.
Test your extension on various types of websites. Test on simple static HTML pages with few images, complex single-page applications with dynamic content, image-heavy sites like photography portfolios, and e-commerce sites with product galleries. Each type of site presents unique challenges for alt text analysis.
Pay special attention to edge cases. Images loaded dynamically through JavaScript, images using lazy loading with placeholder services, images in iframes, and CSS background images all require special handling. Your extension should handle these gracefully without crashing or producing false positives.
Publishing to the Chrome Web Store
Once your extension is tested and polished, you can publish it to the Chrome Web Store. First, create a developer account through the Chrome Web Store Developer Dashboard. There is a one-time registration fee for new developers.
Prepare your extension for publication by creating promotional assets: a compelling icon in multiple sizes, screenshots showing the extension in action, and a detailed description that highlights key features and benefits. Your description should focus on the value users receive, not just technical features.
When submitting, ensure you comply with all Chrome Web Store policies. Your extension must have a clear privacy policy if it collects user data, and it must not contain deceptive or harmful functionality. After submission, Google reviews your extension—this process typically takes a few days to a week.
Conclusion: Empowering Web Accessibility
Building an alt text checker extension is more than just a programming exercise—it is a contribution to making the web more accessible for everyone. By automating the tedious process of checking image alt text, you help developers, designers, and content creators ensure their websites are accessible to all users, regardless of ability.
The skills you develop building this extension transfer directly to other Chrome extension projects and web development work. Understanding how to interact with the DOM, communicate between extension components, and create intuitive user interfaces are valuable skills in any developer’s toolkit.
As web accessibility standards continue to evolve and strengthen, tools like your alt text checker extension become increasingly important. By completing this project, you have not only built a useful developer tool but also contributed to a more inclusive web. Start building today, and help make the internet accessible to everyone.
Technical Deep Dive: Understanding WCAG Guidelines for Alt Text
The Web Content Accessibility Guidelines (WCAG) provide specific requirements for alt text that every developer should understand. WCAG 2.1 Level AA compliance requires that all images of text have appropriate alternative text, and all non-text content has text alternatives. Level AAA requirements are even stricter, requiring long descriptions for complex images.
Understanding the different types of images and their alt text requirements is crucial for building an effective checker. There are three main categories of images that require different handling. Informative images convey simple information or concepts and require descriptive alt text that conveys the image’s meaning or content. Functional images are used as links or buttons and should describe the function rather than the visual appearance. Decorative images serve no informational purpose and should have empty alt attributes (alt=””).
Our extension’s logic should reflect these distinctions. When we encounter an image with alt text that is purely decorative in nature but has descriptive alt text, we might want to flag this as a potential issue, since screen readers will announce this content unnecessarily. Conversely, informative images should never have empty alt text.
Handling Complex Image Scenarios
Real-world web development presents numerous complex scenarios that your alt text checker must handle gracefully. One such scenario involves images within anchor tags. When an image is the only content inside a link, the alt text should describe the link’s destination, not the image itself. This is because screen reader users navigate by links, and they need to understand where each link will take them.
Another complex scenario involves images with dynamic src attributes. Many modern websites use JavaScript to change image sources based on user interactions, responsive breakpoints, or lazy loading. Your content script needs to handle these changes gracefully. One approach is to use a MutationObserver to watch for changes in the DOM and re-analyze when images are added, removed, or modified.
CSS-generated images present another challenge. Some images are set as background-image properties in CSS rather than using img elements. While these are technically not accessible through standard HTML methods, you can extend your extension to check computed styles and identify elements with background images that might need text alternatives.
Performance Optimization for Large Pages
When analyzing pages with hundreds or thousands of images, performance becomes a critical concern. A poorly optimized extension can slow down page loading and consume excessive memory, degrading the user experience rather than improving it.
One optimization technique is to implement pagination in your results display. Rather than showing all findings at once, display them in manageable chunks and load more as the user scrolls. This is especially important for image-heavy sites like e-commerce platforms or media galleries.
Another optimization is to debounce your analysis. If you are implementing real-time scanning as users navigate, wait until the page has finished loading before running your analysis. Use the document.readyState property and listen for the load event to ensure the DOM is complete before scanning.
Consider implementing a caching mechanism to store previous analysis results. If a user revisits a page, you can display cached results instantly rather than re-analyzing. This is particularly useful for large sites that users might browse multiple times during development.
Integrating with Development Workflows
To maximize the value of your alt text checker, consider integrating it with common development workflows. Many teams use continuous integration and continuous deployment (CI/CD) pipelines to automate testing and deployment. You can create a command-line tool or GitHub Action that runs your alt text analysis as part of the build process.
Another integration opportunity is with browser-based development tools. Chrome DevTools already includes an accessibility audit panel, but your extension can complement it with specialized alt text checking. Consider adding a “Copy to Clipboard” feature that allows developers to quickly copy results in formats compatible with issue trackers like Jira or GitHub Issues.
For teams using content management systems, you might build integrations that check images as they are uploaded. This proactive approach catches accessibility issues before they go live, reducing the effort required to fix them later.
Privacy and Security Considerations
When building an extension that analyzes web pages, privacy and security should be top priorities. Your extension will have access to potentially sensitive information, including the content of web pages users visit. It is essential to handle this data responsibly.
Never collect or transmit user browsing data without explicit consent. If you need to store analysis results locally, use Chrome’s storage APIs, which are designed for extension data. Avoid sending page content to external servers unless the user explicitly requests this feature and understands what data will be transmitted.
Be transparent about what your extension does and does not do. Include a clear privacy policy that explains exactly how you handle user data. Users should feel confident that your extension is working to protect their interests, not to exploit their browsing activity.
Future Enhancements and Community Contributions
Building the initial version of your alt text checker is just the beginning. The web accessibility landscape is constantly evolving, and your extension should evolve with it. Consider implementing features that leverage machine learning to suggest better alt text descriptions, automatically generate alt text for simple images, or detect complex images that might benefit from long descriptions.
Opening your project to community contributions can significantly accelerate development. Other developers might contribute new checking rules, translation support, or integration features. Creating a GitHub repository with clear contribution guidelines and a code of conduct helps foster a positive community.
As you continue to develop and refine your extension, you will gain deeper insights into web accessibility challenges and solutions. This knowledge is valuable not just for maintaining your extension but for improving accessibility across all your web development projects.