HTML Guides for img

Every HTML element has an implicit ARIA role defined by the HTML specification. The <img> element's implicit role is img, which means assistive technologies like screen readers already recognize it as an image without any additional ARIA attributes. Adding role="img" explicitly doesn't change behavior — it just adds unnecessary noise to your markup and signals that the author may not understand how native semantics work.

The W3C validator flags this because it violates the first rule of ARIA: don't use ARIA if you can use a native HTML element or attribute that already has the semantics you need. Redundant roles clutter your code, make maintenance harder, and can confuse other developers into thinking the role is there for a specific reason.

The role="img" attribute is genuinely useful in other contexts — for example, when you want to group multiple elements together and have them treated as a single image by assistive technologies. A <div> or <span> has no implicit img role, so adding role="img" to a container is meaningful and appropriate.

How to fix it

Simply remove the role="img" attribute from any <img> element. The image semantics are already built in. Make sure you still provide a meaningful alt attribute for accessibility.

Examples

❌ Redundant role on <img>

<img src="photo.jpg" alt="A sunset over the ocean" role="img">

The validator will warn: The "img" role is unnecessary for element "img".

✅ Fixed: Remove the redundant role

<img src="photo.jpg" alt="A sunset over the ocean">

No explicit role is needed. The browser already communicates this element as an image.

✅ Legitimate use of role="img" on a non-image element

The role="img" attribute is appropriate when applied to a container that groups multiple elements into a single conceptual image:

<div role="img" aria-label="Star rating: 4 out of 5">

<span>⭐</span>

<span>⭐</span>

<span>⭐</span>

<span>⭐</span>

<span>☆</span>

</div>

Here, the <div> has no inherent image semantics, so role="img" is meaningful — it tells assistive technologies to treat the entire group as a single image described by the aria-label.

✅ Another legitimate use: CSS background image with role="img"

<div role="img" aria-label="Company logo" class="logo-background"></div>

Since a <div> styled with a CSS background image has no image semantics, role="img" paired with aria-label ensures the visual content is accessible.

The longdesc attribute dates back to HTML4, where it accepted a URL pointing to a separate page (or section of a page) containing a detailed description of the image. The idea was to supplement the short text in the alt attribute with a more comprehensive explanation, particularly useful for complex images like charts, diagrams, or infographics.

HTML5 made longdesc obsolete for several reasons. Browser support was inconsistent — most browsers never exposed the attribute in a way that was easily discoverable by users. Many developers misused it by placing literal descriptions in the attribute instead of URLs, or left it pointing to broken links. Because the attribute was invisible in the rendered page, there was no visual indication that a longer description existed, making it practically useless for sighted users and unreliable for assistive technology users.

The recommended replacements are more robust and accessible:

• Wrap the image in an a element (or place a link nearby) that points to the description page. This makes the link visible and usable by everyone.
• Use aria-describedby to reference a description that already exists on the same page. This is ideal when the detailed description is displayed alongside the image.
• Use a figure with figcaption to associate a visible caption or description directly with the image.

These approaches are better for accessibility because they work reliably across browsers and assistive technologies, and they make the description discoverable to all users, not just those using specific screen readers that happened to support longdesc.

Examples

❌ Obsolete: using longdesc

<img

src="cat.jpg"

alt="Smiling cat sitting on a windowsill"

longdesc="descriptions/smiling-cat.html">

This triggers the validation error because longdesc is no longer a valid attribute on img in HTML5.

✅ Fix: wrap the image in a link

The simplest replacement is to make the image itself a link to the description:

<a href="descriptions/smiling-cat.html">

<img src="cat.jpg" alt="Smiling cat sitting on a windowsill">

</a>

✅ Fix: provide a separate link near the image

If you don't want the image itself to be clickable, place a visible link nearby:

<figure>

<img src="chart.png" alt="Quarterly revenue chart for 2024">

<figcaption>

Quarterly revenue chart.

<a href="descriptions/revenue-chart.html">View detailed description</a>

</figcaption>

</figure>

✅ Fix: use aria-describedby for on-page descriptions

When the long description is already on the same page, reference it with aria-describedby:

<figure>

<img

src="chart.png"

alt="Quarterly revenue chart for 2024"

aria-describedby="chart-description">

<figcaption id="chart-description">

Revenue grew from $2.1M in Q1 to $3.8M in Q4, with the largest

quarter-over-quarter increase occurring between Q2 and Q3.

</figcaption>

</figure>

This approach keeps the description visible on the page and programmatically associates it with the image for screen readers.

Choosing the right approach

In all cases, make sure the alt attribute still provides a meaningful short description. The long description supplements alt — it doesn't replace it.

The name attribute on the <img> element is obsolete in HTML5 and must be replaced with the id attribute.

Older pages used <img name="logo"> so scripts could reach the image through document.images["logo"], a pattern common in pre-DOM rollover scripts. HTML5 dropped the attribute. An id serves the same purpose: document.getElementById("logo") finds the image, and document.images also indexes images by their id.

The name attribute is still valid on elements like <input>, <form>, <meta>, and <map>, where it has a distinct function. On <img>, though, it has no valid use in modern HTML.

Invalid example

<img src="logo.png" name="logo" alt="Acme logo">

Valid example

<img src="logo.png" id="logo" alt="Acme logo">

Any script that referenced the image as document.images["logo"] keeps working with the id in place, or can switch to document.getElementById("logo").

The name attribute was historically used on img elements to reference images through JavaScript's document.images collection or via document.getElementsByName(). In early HTML, name served as an identifier for various elements before the id attribute was widely adopted. The HTML living standard (WHATWG) now marks name as obsolete on img elements, meaning it should no longer be used in new content.

This matters for several reasons:

• Standards compliance: Using obsolete attributes means your HTML does not conform to the current specification, which can cause validation errors and may lead to unexpected behavior in future browser versions.
• Consistency: The id attribute is the universal mechanism for uniquely identifying any HTML element. Using id instead of name keeps your markup consistent and predictable.
• JavaScript and CSS targeting: Modern APIs like document.getElementById() and document.querySelector() work with id, not name on image elements. CSS selectors also target elements by id (e.g., #myImage), making id the more versatile choice.
• Fragment linking: The id attribute allows you to link directly to an element using a URL fragment (e.g., page.html#myImage), whereas the obsolete name attribute on img does not serve this purpose.

To fix this issue, simply replace name with id on your img elements. Keep in mind that id values must be unique within the entire document — no two elements can share the same id. If you have JavaScript code that references the image by name (e.g., document.images["myImage"] or document.getElementsByName("myImage")), update those references to use document.getElementById("myImage") or document.querySelector("#myImage") instead.

Examples

Incorrect: using the obsolete name attribute

<img src="photo.jpg" name="heroImage" alt="A sunset over the ocean">

This triggers the validation error because name is no longer a valid attribute on img.

Correct: using the id attribute

<img src="photo.jpg" id="heroImage" alt="A sunset over the ocean">

The name attribute is replaced with id, and the element can now be targeted with document.getElementById("heroImage") or the CSS selector #heroImage.

Updating JavaScript references

If your existing code references the image by name, update it accordingly.

Before (relying on name):

<img src="logo.png" name="siteLogo" alt="Company logo">

<script>

var logo = document.images["siteLogo"];

logo.style.border = "2px solid blue";

</script>

After (using id):

<img src="logo.png" id="siteLogo" alt="Company logo">

<script>

var logo = document.getElementById("siteLogo");

logo.style.border = "2px solid blue";

</script>

Multiple images that previously shared a name

Since id values must be unique, you cannot give the same id to multiple elements. If you previously used the same name on several images and selected them as a group, switch to a shared class instead:

<img src="slide1.jpg" class="gallery-image" alt="Mountain landscape">

<img src="slide2.jpg" class="gallery-image" alt="Forest trail">

<img src="slide3.jpg" class="gallery-image" alt="River valley">

<script>

var images = document.querySelectorAll(".gallery-image");

images.forEach(function(img) {

img.style.borderRadius = "8px";

});

</script>

This approach is standards-compliant and gives you flexible, modern element selection using class for groups and id for unique elements.

The sizes attribute has a value starting with auto, but the image is not lazy-loaded. A sizes value of auto only works together with loading="lazy".

sizes="auto" tells the browser to pick the srcset candidate that matches the image's actual rendered width, instead of you writing out media conditions by hand. The browser can only know that width after it has laid the image out on the page, which is exactly the point at which a lazy-loaded image is fetched. For an image that loads eagerly, the width is not available in time, so the specification restricts auto to elements that also carry loading="lazy".

To fix the error, add the loading attribute to the same element:

<img

srcset="photo-400.jpg 400w, photo-800.jpg 800w"

sizes="auto"

loading="lazy"

alt="A field of sunflowers">

If the image needs to load eagerly, for example a hero image above the fold, drop auto and give sizes an explicit value instead:

<img

srcset="photo-400.jpg 400w, photo-800.jpg 800w"

sizes="(max-width: 600px) 400px, 800px"

alt="A field of sunflowers">

A sizes value that starts with auto lets the browser work out an image's display size on its own, but the specification only permits it when the same <img> is lazy-loaded with loading="lazy".

The auto keyword removes the need to hand-write media-condition source sizes for a responsive image. For the browser to measure the rendered width and pick a candidate from srcset, the layout around the image has to already exist when the image is fetched. That holds for a lazy-loaded image, which is requested only as it approaches the viewport. An eagerly loaded image can be fetched before its box is laid out, so auto would have nothing to measure, and the validator rejects it.

To fix the error, add loading="lazy" to the same <img>. If the image has to load eagerly, such as a hero image at the top of the page, drop the auto keyword and give sizes explicit lengths instead.

Invalid example

<img

srcset="small.jpg 480w, large.jpg 1024w"

sizes="auto"

src="large.jpg"

alt="Product photo">

Valid example

<img

srcset="small.jpg 480w, large.jpg 1024w"

sizes="auto"

loading="lazy"

src="large.jpg"

alt="Product photo">