Image Alt Text Implementation (WCAG)
Alt text (the alt attribute) is a text alternative to an image. Screen readers announce it instead of showing the picture. Search engines use it for indexing. WCAG SC 1.1.1 requires alt for all non-text elements.
Alt Text Writing Guidelines
Informative images — describe content and function:
<!-- Bad -->
<img src="photo.jpg" alt="photo">
<img src="chart.png" alt="chart">
<!-- Good -->
<img src="ceo-photo.jpg" alt="Ivan Petrov, company CEO">
<img src="revenue-q3.png" alt="Q3 2024 revenue chart: 35% growth compared to Q2">
Decorative images — use empty alt, not absent:
<!-- Correct — empty alt, screen reader skips -->
<img src="bg-pattern.svg" alt="">
<!-- Wrong — without alt screen reader announces filename -->
<img src="bg-pattern.svg">
Functional images (buttons, links) — describe the action:
<a href="/home">
<img src="logo.svg" alt="Go to home page">
</a>
<button>
<img src="search-icon.svg" alt="Search">
</button>
Images with text — alt must contain that text:
<img src="sale-banner.jpg" alt="Discounts up to 50% on all items until December 31">
CMS Implementation
// Require alt when uploading images
class ImageUploadRequest extends FormRequest
{
public function rules(): array
{
return [
'image' => 'required|image|max:5120',
'alt_text' => 'required|string|max:255|min:5',
];
}
public function messages(): array
{
return [
'alt_text.required' => 'Provide image description for accessibility',
];
}
}
{{-- Show warning about missing alt in WYSIWYG editor --}}
@if (!$image->alt_text)
<div class="alert alert-warning" role="alert">
Image without alt text — add description for accessibility
</div>
@endif
Image Component in React
interface ImageProps {
src: string;
alt: string; // required prop
decorative?: boolean;
}
function Image({ src, alt, decorative = false }: ImageProps) {
// If decorative — force empty alt and role="presentation"
if (decorative) {
return <img src={src} alt="" role="presentation" />;
}
return <img src={src} alt={alt} />;
}
// TypeScript won't let you forget alt
// <Image src="photo.jpg" /> — compiler error
// <Image src="photo.jpg" alt="Description" /> — ok
Image Audit Without Alt
# Find images without alt in templates
grep -rn '<img' resources/views/ | grep -v 'alt='
# axe-core in Playwright
test('all images have alt text', async ({ page }) => {
await page.goto('/');
const violations = await checkA11y(page, null, {
runOnly: ['image-alt'],
});
expect(violations).toHaveLength(0);
});
Timeline
Audit and add alt text to existing project: 1–3 days depending on image count. Set up required alt in CMS — half a day.