How to Add Alt Text to Website Thumbnail Images in a Directory

Alt text is set where a website outputs an image, not by putting text in the image directory. Add it to the CMS media record, the content block or field that uses the image, or the HTML template. Then inspect the rendered thumbnail to confirm the <img> has the right alt value for its purpose in that location.

A directory contains image files; a filename or folder path does not provide a considered text alternative. If a thumbnail conveys information, describe the relevant content. If it is a link, make its alternative communicate the link’s destination or function. If it is purely decorative and adds nothing, use an empty value: alt="".

1. Choose alt text for the thumbnail’s purpose

Before editing, answer: what would a person who cannot see this thumbnail need to know here? Describe that information or function concisely. Avoid repeating nearby text that already gives the same information, and do not use a filename as a substitute for deciding what the image means in context.

Thumbnail use	What to put in `alt`
Informative image	A concise equivalent for the relevant visual information.
Image links to an article or product	The linked destination or action, especially if the image is the link’s only content.
Decorative image beside equivalent text	An empty alternative, `alt=""`, so it can be skipped.
Thumbnail whose meaning changes by placement	Review or override the shared description to fit that use.

A useful test is to imagine replacing the image with its alt text: the page’s meaning should remain intact. The same file can need different alternatives in different contexts, so reusable media metadata is a starting point, not a guarantee that every placement is correct.

2. Find where the directory image is used

First identify how the page gets the thumbnail. Search the CMS content or template for the image, filename, attachment ID, media entity, or path. Then update the source that controls its rendered alt attribute.

Locate a page showing the thumbnail and record its image path or media record.
Determine whether the image is managed by WordPress, Drupal, another CMS, or a template that writes HTML directly.
Update the alt text in that system’s source field or output code.
Open the rendered page and inspect the image in its actual context.
Check desktop and mobile placements, linked behavior, and repeated uses of the same image.

Changing a filename, moving a file into another directory, or generating a smaller image does not itself set useful alt text. Image transformations affect the asset’s display; the website still needs to output the intended alternative.

3. WordPress: set media alt text and check the block

Open Media → Library and select the image, or open its Edit Media screen.
Enter the description in Alternate text and save.
Open the page or post where the thumbnail appears. If it is an Image Block, inspect the block’s own alt text and adjust it when that placement has a different purpose.
View the published page and verify the output, including any linked thumbnail.

WordPress creates smaller image sizes for use as thumbnails, but those are still image elements in the page. Check the rendered image rather than assuming the attachment filename, directory, or generated size supplies its text alternative. A theme or custom template may also affect how the image is output.

4. Drupal: keep the image field, style, and alternative separate

Identify the image field attached to the relevant content type or media workflow.
When adding or editing the image on content, enter the alternative text in the image field.
Use the image style to control display transformations such as scaling or cropping; do not treat the style or storage directory as alt text.
Inspect the rendered page to confirm the resulting image has the expected alternative.

Drupal’s image field can have a default directory for uploaded files, while image styles control how generated display images are transformed. Those settings are distinct from the text alternative entered for the image on content. On an established Drupal 10 or 11 site, the Image Alt Fallback project documents a filterable media table and configurable behavior for empty alternatives. Treat a fallback as a transitional safety net: store meaningful text on the media or file record where appropriate, and check the project’s current compatibility and configuration before adopting it.

5. Direct HTML and templates: write the attribute explicitly

For an informative thumbnail, include a concise alternative. For a decorative one, include an empty attribute. If the thumbnail is linked, make its alternative communicate the link’s purpose when that image supplies the link’s accessible name.

<!-- Informative thumbnail -->
<img src="/images/river-bridge-thumb.webp" alt="A stone bridge crossing the river at dusk">

<!-- Decorative thumbnail beside an equivalent article title -->
<img src="/images/article-card-decoration.webp" alt="">

<!-- Image-only link: name the destination or action -->
<a href="/articles/river-restoration/">
  <img src="/images/river-restoration-thumb.webp" alt="Read about the river restoration project">
</a>

In a server-rendered template, use the value from the relevant content or media record and escape it for the HTML attribute. For example, a template should output the equivalent of <img src="..." alt="...">; the path is not a substitute for the description. In JavaScript, set the DOM property or attribute from the same source field:

const thumbnail = document.querySelector(".article-thumbnail");
thumbnail.alt = "A stone bridge crossing the river at dusk";

Prefer setting the value when rendering from content data instead of adding a late client-side patch, which may not be present in the initial HTML or may run after assistive technology has inspected the page. Never omit the attribute merely because the image is a thumbnail; decide whether it needs an informative or empty alternative.

6. Audit many thumbnails in a directory

A directory-wide review can find likely omissions, but no automated script can reliably decide an image’s purpose from its pixels or filename alone. Use automation to identify rendered images without an alt attribute, then review each use in context.

Collect image paths used by the site, not only every file on disk. Unused assets do not need page alternatives.
Find pages or templates that render those images and inspect the generated HTML.
Flag missing alt attributes separately from empty ones. An empty value can be correct for decorative images.
Review linked thumbnails and images that repeat nearby titles; decide whether each is informative, functional, or decorative.
Save descriptions in the CMS or content source and add regression checks to the content workflow if useful.

Do not bulk-fill every blank value with a filename. That can produce noisy, misleading alternatives and can make decorative images needlessly announced. A fallback that derives text from a filename is only a stopgap and should be reviewed by a person.

7. Verify the rendered thumbnail

After updating the source, inspect the page HTML or use browser developer tools to confirm the exact image element has an alt attribute. Check the thumbnail at its actual placement, including whether the image is inside a link and whether nearby visible text already names the destination.

Informative image: the rendered text conveys the important visual information.
Decorative image: the attribute is present and empty, alt="".
Image-only link: the link has a meaningful accessible name from the image alternative or another suitable label.
Responsive or generated thumbnail: the displayed image still has the expected alternative.
Repeated media item: each placement has been checked for context-specific meaning.

8. Troubleshooting

Symptom	Likely cause	Fix
The image is announced by its filename	The `alt` attribute is missing, or the CMS did not save the value.	Edit the source media or content field, save it, and inspect the rendered HTML for the attribute.
The media record has alt text, but the page does not	A block override, theme template, custom renderer, or cache may be controlling the output.	Inspect the specific page block and rendered image, update the active output source, then clear the relevant cache if needed.
A decorative thumbnail is read aloud	It has descriptive text even though it adds no information, or the attribute is missing.	Use `alt=""` when equivalent content is already available and the image is purely decorative.
A linked thumbnail has no useful link name	The image is the only link content and its alternative describes appearance rather than destination or action.	Describe the destination or function in the alternative, or provide another accessible name for the link.
Only one size or placement has the expected alt text	Different blocks, templates, or image renderers may use different fields or overrides.	Check every rendered use, including responsive output and generated thumbnail sizes.
Drupal fallback fills an empty alternative with poor text	A fallback may derive a generic value from a filename or other default.	Use fallback behavior only as a temporary safety net and add meaningful text to the source media or file record.
Updated text does not appear after saving	The page or media output may be cached, or a different record is used than the one edited.	Confirm the attachment or media ID, refresh the relevant cache, and recheck the page source.

9. Performance, reliability, and maintenance

Alt text is a small HTML attribute and does not change image file size or thumbnail generation. The main reliability concern is keeping the text attached to the same content source that renders the image. Store it in CMS media metadata or the content record, and check templates that bypass the standard renderer.

For large directories, prioritize images actually used on public pages, then review missing attributes and context separately. Automated checks can catch omitted attributes, but they cannot reliably distinguish an informative image from a decorative one or infer a linked thumbnail’s purpose. Include rendered-page review in publishing and template changes so generated sizes and custom blocks do not silently lose the value.

Or skip the browser setup

If you need a clean screenshot of the page after fixing the thumbnail, [ScreenshotNeo](https://screenshotneo.com) captures a URL through one API request. It is a screenshot API and MCP server from Yorker Media. Its capture options include full-page shots, custom viewport and device presets, custom CSS and JavaScript, and waits for a selector, delay, or network idle. See the ScreenshotNeo API documentation for request parameters.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://example.com/article \
  -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com/article"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com/article'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot, and each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers report the page verdict and billing status. An MCP server lets AI agents use screenshot, page-info, and PDF tools. The free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month with no card.

FAQ

Can I set alt text on a folder?

No. A folder stores files; the text alternative belongs to the content or markup that outputs each image.

Should I use the image filename as the alt text?

Only if it happens to be a clear, accurate description of the image’s purpose in that placement. Filenames are not a reliable substitute for reviewing context.

Does a thumbnail need alt text if the full-size image has it?

The rendered thumbnail is still an image element. Confirm that the page output includes the appropriate alternative, whether sourced from shared media metadata or a context-specific value.

Is empty alt text the same as missing alt text?

No. alt="" explicitly marks an image as having no text alternative to announce, which is appropriate for a purely decorative image. Missing the attribute leaves that decision unclear.