Every image on a WordPress site should have descriptive alternative text — a brief written description that tells screen reader users and search engines what the image shows. WordPress image alt text is both an accessibility requirement under WCAG guidelines and an SEO factor that helps search engines understand image content for image search ranking. Getting alt text right requires understanding what to write, where to add it in WordPress, and how to audit existing images efficiently. We go deeper on the whole subject in our Complete Guide to WordPress How.
WordPress Image Alt Text — What Good Alt Text Looks Like
Good WordPress image alt text describes the content and function of the image in a way that makes sense to someone who cannot see it. The description should be concise (typically 5–15 words), specific rather than generic, and contextually relevant to the surrounding content.
Bad alt text examples: “image” (completely uninformative), “photo” (describes the medium, not the content), “DSC00234.jpg” (the filename), “WordPress tutorial” (too generic), “Click here” (describes action, not image). Good alt text for the same image: “WordPress admin dashboard with the Plugins menu open showing 3 available updates” — this tells screen reader users exactly what they would see if they could view the image, and gives search engines meaningful keyword context about what the image depicts.
Decorative images — purely visual design elements that add no informational content — should have empty alt text (alt=””) rather than descriptive text. An empty alt attribute signals to screen readers that the image should be skipped entirely, preventing the reader from announcing “graphic” or the image filename for an image that has no meaningful content for the user. Decorative images include: background patterns, decorative borders, spacer images, and stock photos used purely for visual impact without conveying specific information. For all other images, descriptive WordPress image alt text is required. According to the W3C Web Accessibility Initiative, the alt text decision tree is: if the image is decorative, use empty alt. If the image is functional (a button or link), describe the function. If the image conveys information, describe the information. If the image is complex (a chart, diagram, or map), provide both alt text and a longer description in the surrounding content.
Adding Alt Text in WordPress
Multiple locations in WordPress accept WordPress image alt text — in the Media Library for the image’s default alt text, and in the block editor for overrides on specific instances of the image in content.
Set WordPress image alt text in the Media Library (applies globally whenever the image is inserted): Media → Library → click any image → the Attachment Details panel opens → Alt Text field → enter the description → Save. This alt text automatically populates whenever the image is inserted into a post or page, saving repetitive entry for images used in multiple locations. For featured images, the alt text must be set in the Media Library — the block editor’s Image block setting does not apply to featured images; featured images use the alt text stored in the Media Library attachment record.
Override alt text for a specific image instance in the block editor: insert an Image block → click the image → the Block settings panel on the right → “Alt text (alternative text)” field → enter a context-specific description that may differ from the Media Library default. Overriding at the block level is appropriate when the same image is used in different contexts where different descriptions are more accurate — a screenshot used in a tutorial post needs different alt text than the same screenshot used in a product comparison table. The block-level WordPress image alt text override takes precedence over the Media Library default for that specific image instance only, without changing the default for other uses of the same image. Our guide on WordPress accessibility covers the full WCAG compliance requirements that apply to images alongside the alt text practices described here — alt text is one component of a broader accessibility implementation that also includes heading hierarchy, keyboard navigation, and colour contrast.
Alt Text for Different Image Types
Different image types require different WordPress image alt text approaches — the correct alt text for a product photo is different from the correct alt text for an infographic, a person’s headshot, or a screenshot.
Product WordPress image alt text: describe key visual attributes — “Blue wireless headphones with over-ear design and foldable headband” rather than just “headphones” or the product name alone. If the image shows a feature, describe the feature: “Close-up of the noise cancellation button on the left ear cup.” Product alt text that includes relevant descriptive terms (colour, material, size indication, key features) aligns the image’s SEO with the product queries customers use when searching.
Infographics and charts need WordPress image alt text that summarises the main finding or conclusion, not describe each element: “Bar chart showing WordPress powers 43% of all websites as of 2024” rather than “bar chart with blue bars.” If the chart is complex with multiple data series, provide the alt text summary and include the underlying data in a nearby table or text description for full accessibility. Screenshots: describe what the screenshot shows and what the viewer should notice — “WordPress admin Plugins page showing Akismet plugin with deactivate and settings links highlighted” provides the context that makes the screenshot’s purpose clear. Headshots and person photos: use the person’s name and context — “Jane Smith, WordPress developer, speaking at WordCamp Europe 2024.” For WordPress image alt text on stock photos used to illustrate concepts, the alt text should describe what the image depicts rather than the abstract concept it is illustrating — “Two people shaking hands across a conference table” rather than “business partnership.”
Auditing Existing WordPress Images for Missing Alt Text
Most established WordPress sites have hundreds or thousands of images, many uploaded before alt text was prioritised. A systematic WordPress image alt text audit identifies which images are missing descriptions and provides a prioritised list for remediation.
Audit WordPress image alt text using the Media Library List view → the Alt Text column shows the alt text for each image (or blank if none is set). Click any image with no alt text → add the description → Save. This manual audit works for small media libraries but becomes impractical for sites with thousands of images. For large-scale audits, use the Accessibility Checker plugin (free) by Equalize Digital — it scans all published posts and pages, identifies images with missing alt text in the content, and provides a list of all issues sorted by page and image. This automated audit produces an actionable remediation list without manually checking each image individually.
WP-CLI provides the most efficient WordPress image alt text bulk audit for sites with server access: wp post list --post_type=attachment --post_mime_type=image --meta_query='[{"key":"_wp_attachment_image_alt","compare":"NOT EXISTS"}]' --fields=ID,post_title --format=table — this lists all image attachments that have no alt text meta value set, providing the IDs for direct remediation. For bulk update of a specific alt text pattern (adding the filename-based alt to all images as a starting point for manual refinement): wp post list --post_type=attachment --post_mime_type=image --fields=ID,post_title | while read id title; do wp post meta set $id _wp_attachment_image_alt "$title"; done. The filename or title is a poor final alt text but better than nothing as a starting point — add the WP-CLI audit output to a spreadsheet and distribute alt text writing tasks to content team members who can add accurate descriptions based on each image’s content. Our guide on WordPress GDPR compliance covers the image metadata considerations that overlap with alt text management — properly attributed and described images are part of a complete content governance strategy that also addresses copyright, personal data in images, and consent requirements for identifiable person photos.
Alt Text SEO Impact and Best Practices
WordPress image alt text contributes to SEO beyond accessibility to search engine optimisation — specifically image search rankings and the contextual signals that search engines use to understand page content. Correctly written alt text improves both.
Image search ranking: Google Image Search ranks images based on alt text, surrounding text, image file name, and page context. An image with descriptive alt text that matches what users search for in image search appears higher in image results. For sites where image search drives meaningful traffic (photography portfolios, recipe sites, product ecommerce, real estate listings), high-quality WordPress image alt text is a direct revenue driver. Name image files descriptively before uploading (use-dashes-between-words.jpg rather than IMG_4523.jpg) — the file name and the alt text together send stronger signals than either alone.
Keyword density in alt text: while alt text is a legitimate place to include relevant keywords, keyword stuffing in alt text is a Google Webmaster Guidelines violation. “WordPress dashboard with plugins menu, WordPress plugin update, WordPress plugin management, WordPress admin” is keyword stuffing disguised as a description. “WordPress admin dashboard showing the Plugins menu with available updates highlighted” is a legitimate description that naturally includes relevant keywords without manipulation. Write alt text for humans first — if it sounds like a natural description a sighted person would give, it is almost certainly not spam. The WordPress image alt text that works best for both accessibility and SEO is always genuinely descriptive of the image content rather than optimised for keyword density. One image with several relevant descriptive words naturally contains more SEO value than an image with a single generic label, and good descriptions naturally incorporate the terminology users search for without any artificial keyword insertion. Reviews from Google’s web developer documentation on image SEO best practices confirm that descriptive, non-keyword-stuffed alt text that accurately describes image content is the standard they recommend for both accessibility compliance and image search performance. Our guide on creating a WordPress XML sitemap covers image sitemap configuration that works alongside WordPress image alt text to provide search engines with both discovery signals and descriptive metadata for all images on the site.
Bulk updating WordPress image alt text programmatically for an existing content library uses the update_post_meta() function to set the _wp_attachment_image_alt meta key for each image attachment. A PHP script run via WP-CLI’s eval command can update all images in a specific category, date range, or based on other criteria — for example, updating all images whose alt text is empty or whose alt text matches the generic filename pattern. Before running any bulk update, test on a development environment and back up the database — a bulk update that sets incorrect alt text on thousands of images requires a database restore to revert. The Image SEO Booster plugin provides a GUI for bulk alt text management without custom code, allowing pattern-based alt text generation (using the image filename, post title, or custom fields as the alt text source) with a preview before committing the changes. For content teams managing ongoing WordPress image alt text quality, integrating an alt text quality check into the editorial workflow (requiring alt text before a post can be published) prevents the accumulation of images with missing or poor alt text that requires later bulk remediation.
AI-generated WordPress image alt text is an emerging solution for large media libraries where manual alt text writing is impractical. Several WordPress plugins now integrate with AI image recognition APIs (Google Cloud Vision, Microsoft Azure Computer Vision, OpenAI’s vision models) to automatically generate alt text suggestions when images are uploaded to the Media Library. The generated alt text is saved as a suggestion for editorial review rather than immediately published — a human editor reviews and refines the AI description before saving it. This hybrid approach — AI-generated first draft, human refinement — scales alt text production significantly compared to purely manual writing while maintaining quality above purely automated generation that often produces generic or inaccurate descriptions. For WordPress sites uploading dozens of images daily (news sites, product catalogues, photography portfolios), AI-assisted alt text generation is the only practical path to comprehensive WordPress image alt text coverage without a dedicated alt text writing resource. Our guide on implementing WordPress lazy load covers the image delivery optimisation that pairs with alt text quality — images with correct dimensions specified in the alt text’s surrounding HTML and properly described in alt text contribute to both accessibility scores and Core Web Vitals performance metrics simultaneously.
Testing WordPress image alt text implementation correctness uses multiple verification methods: browser DevTools (right-click any image → Inspect → the img element’s alt attribute shows the current alt text), the WAVE accessibility browser extension (overlays alt text information directly on the page with green icons for correct alt and yellow/red for issues), and Google Search Console’s Mobile Usability or URL Inspection reports which flag images with missing alt attributes on specific pages. Running WAVE on the homepage and one representative post after implementing alt text additions provides immediate visual confirmation that the correct alt text appears on each image without requiring source code inspection. For ongoing monitoring, the Accessibility Checker plugin (mentioned in the audit section) can be set to run automated scans and generate reports identifying new posts with WordPress image alt text issues, creating a continuous quality gate rather than a one-time audit exercise.
