How to Display Image Instead of Text in HTML: Fix img src and Alt Text

When the browser outputs alt text instead of the image

A browser outputs alt text instead of an image when a network request fails, a file path is broken, or assistive software requests textual alternatives. The alt attribute provides an essential fallback mechanism that preserves page meaning when the visual media cannot be retrieved.

When an image file fails to load during the time a page loads, the browser falls back on the alternative text string. Normative guidance from the W3C Web Accessibility Initiative (WAI) establishes that this mechanism guarantees content visibility for visually impaired users relying on screen readers, and MDN Web Docs confirms that the browser may substitute the alt value when the resource errors out, is blocked, or has not finished loading. If an image source returns a server error or an invalid file path, the text defined in the alt attribute is rendered directly in the visual layout box reserved for that media.

The scale of the problem is measurable rather than theoretical:

Teams that regularly prepare graphics for publication, from screenshots to product renders, often standardise their asset pipeline first; a practical overview of production tooling is collected in this guide to online photo editors. Teams whose pipeline also produces motion assets usually hit the same naming and export questions, which is why the trade-offs in free video editing apps like capcut tend to surface in the very same sprint.

How to tell a load error from a text caption

An image loading error displays broken image icon boundaries along with the alt text, whereas a regular text caption resides in separate semantic tags like <figcaption>. Developers can inspect the element in DevTools to confirm whether visible text originates from an alt attribute or neighboring DOM elements.

In Chrome DevTools, network failures such as 404 Not Found or cross-origin restrictions appear highlighted in red within the Network panel; cross-origin rejections are labelled explicitly as CORS error, while a true transport failure is reported as a failed request without a CORS message. Select the request and read the Status, Response Headers, and Initiator columns to separate a missing file from a blocked one. In contrast, visible text wrapped in a paragraph or caption tag renders independently of the image's network status. Distinguishing between fallback text and the optional title attribute is equally straightforward: the title attribute displays only as a hover tooltip and never replaces an image upon a loading failure.

A fast three-step DevTools routine:

1. Elements panel- select the <img> node and confirm the resolved currentSrc value.
2. Network panel- filter by Img, reload with cache disabled, and read the status code.
3. Console panel- look for mixed-content warnings, Content-Security-Policy img-src violations, and CORS messages.

Two minutes, three panels. That routine resolves most tickets before anyone opens the repository.

Minimal example of img src and alt attribute

The minimal W3C-compliant structure for displaying an image requires only the img tag name alongside the src and alt attributes. This structure provides both the resource locator and the required textual substitute in a single line.

<img src="logo.png" alt="Company Logo">

In this syntax, img src defines the path to the target image resource inside the current html file. The alt text ensures that if the image file becomes unreachable, the string "Company Logo" takes its place seamlessly. The W3C Nu HTML Checker reports a missing alt attribute as a validation error, which makes alt presence the machine-testable minimum for a conforming img element.

Image size via the width and height attributes

Specifying explicit width and height attributes on the img element reserves appropriate layout space before the image binary finishes loading. This practice prevents unexpected layout jumps and reduces Cumulative Layout Shift (CLS) on the web page.

Setting explicit numerical dimensions allows modern browsers to calculate the intrinsic aspect ratio immediately when the page loads, which is why Google's Web Vitals documentation instructs authors to always include size attributes on image and video elements.

<img src="banner.jpg" alt="Annual financial metrics overview" width="1200" height="600">

Assigning clear height attributes and width values prevents surrounding text from collapsing into the image area while the browser fetches the visual resource over the network.

Width/height attributes versus CSS: which one wins. HTML width and height attributes are presentational hints with the lowest priority. If your stylesheet contains a global rule such as img { width: 100%; }, it overrides width="500" and the image may be stretched or distorted. This catches people out constantly, and the symptom looks nothing like a broken path.

<!-- Attribute may be overridden by a global CSS rule -->
<img src="html5.gif" alt="HTML5 icon" width="128" height="128">
<!-- Inline style takes precedence over the stylesheet rule -->
<img src="html5.gif" alt="HTML5 icon" style="width:128px; height:auto;">
<!-- Modern, responsive-safe approach: keep attributes AND lock the ratio in CSS -->
<style>
  .fixed-ratio { width: 100%; height: auto; aspect-ratio: 2 / 1; }
</style>
<img src="banner.jpg" alt="Annual financial metrics overview"
     width="1200" height="600" class="fixed-ratio">

Keep the numeric attributes for CLS reservation, then control the rendered size with CSS width, height, or aspect-ratio. Never rely on attributes alone when a global stylesheet manipulates image dimensions.

Preloading critical images and cache busting

Two infrastructure-level techniques prevent the two remaining causes of "text instead of image": a critical hero graphic that arrives too late, and a stale cached file that no longer exists.

<!-- Preload an above-the-fold image so the browser fetches it early -->

<link rel="preload" as="image" href="/assets/hero-banner-v2.webp">

<!-- Cache busting through fingerprinted filenames -->
<img src="/assets/logo-v1.0.4.png" alt="Company logo" width="240" height="60">
<img src="/assets/hero.9f2c41ab.webp" alt="Product overview" width="1600" height="900">

Versioned or hash-fingerprinted filenames are safer than query-string cache breakers: intermediate CDNs and some proxies ignore query parameters, whereas a new filename is unambiguously a new resource. During testing, force a hard reload with Ctrl+Shift+R (Windows) or Cmd+Shift+R (macOS) so the browser does not serve an outdated 304 response. Adding file-hash comparisons to the deployment pipeline confirms that the correct, updated binaries were actually published after each release.

If assets are delivered programmatically rather than committed by hand, the same versioning discipline belongs in the delivery layer; teams building that layer usually start from the api contract and let filenames be generated, never typed.

Relative paths to an image inside the site folder

A relative file path locates an image file based on the current location of the html file in the directory tree. Relative paths are portable across different local development servers and production domains.

Relative paths resolve against the current document location, so moving an HTML file or changing a framework route can break them silently. Root-relative paths starting with / resolve from the domain root and are usually more stable, but they remain tied to your deployment layout: markup that works on localhost:3000 can fail in production when build output directories differ.

When referencing src images in nested directories, matching letter casing is critical. Operating systems like Linux strictly enforce case sensitivity, meaning Image.PNG and image.png represent two distinct file references, while macOS and Windows are frequently case-insensitive by default.

Absolute URLs and external images over HTTPS

An absolute path references external images by specifying the full network URL, including the protocol, domain name, and exact file location. Absolute paths are commonly used when embedding graphics hosted on dedicated media servers or external CDNs.

<img src="https://example.com/images/vector-diagram.svg" alt="Diagram showing network architecture">

When referencing external images on secure web pages, the src https URL protocol must be used. Loading an HTTP image link on an HTTPS secure web page creates a mixed content warning, causing modern browsers to block image loading entirely to safeguard security.

Also confirm that no Content-Security-Policy img-src directive blocks the external host: a CSP violation prevents the request from being issued at all, and the browser falls back to alt text exactly as it would on a 404. Worth noting, the console message differs, so read it rather than guessing.

File names, extensions, and file format

Mismatching the target file name or extension in the src attribute causes the web browser to throw a 404 error and render jpg alt or png alt text instead. Web servers require exact alignment between the HTML reference and the file stored on disk.

Common supported image file formats include:

• JPEG / JPG Standard for photographs (jpg alt).
• PNG Suitable for graphics requiring transparency (png alt).
• WebP / AVIF Modern compressed web formats for fast loading.
• SVG Scalable vector graphics ideal for logos and icons.
• GIF / APNG Animated raster formats supported across all major browsers.

Verifying an external image URL

Testing an external image URL directly in a browser address bar confirms whether the remote server yields a successful HTTP status code. If the direct request returns a 200 OK response, the image binary is intact and publicly accessible. RFC 9110 defines 200 OK as a successful response, and a HEAD request returns the same headers without transferring the binary, which is ideal for bulk availability checks.

Terminal Command for Direct Server Verification:

curl -I https://example.com/images/sample-graphic.png

If the response header displays 403 Forbidden or lacks appropriate Cross-Origin Resource Sharing (CORS) headers, the hosting server is actively blocking external domains from embedding its media. A cross-origin rejection typically appears in the console as:

Access to image at 'https://cdn.example.com/image.jpg' from origin

'https://example.com' has been blocked by CORS policy

Server-side remediation, by cause:

# 1. Allow cross-origin consumption of images (Nginx)
location ~* \.(png|jpg|jpeg|webp|avif|svg)$ {
    add_header Access-Control-Allow-Origin "https://example.com";
    add_header Cross-Origin-Resource-Policy "cross-origin";
    add_header Cache-Control "public, max-age=31536000, immutable";
}
# 2. Return correct MIME types
types {
    image/png   png;
    image/webp  webp;
    image/avif  avif;
    image/svg+xml svg svgz;
}

Use crossorigin="anonymous" on the <img> element only when the pixels must be read programmatically, for example when drawing the image into a <canvas>. Addressing server permissions and headers restores the graphic view on your web page.

Client-side fallback: replacing a broken image with JavaScript

Browser-level fallback shows alt text, but production interfaces often need a visual placeholder instead of an empty frame. The onerror event handler swaps the broken source for a known-good asset:

<!-- Automatic replacement of a broken image with a fallback PNG -->
<img src="products/item-404.jpg"
     onerror="this.onerror=null; this.src='/assets/images/placeholder.png';"
     alt="Product photo of the ergonomic mesh office chair"
     width="600" height="400">

Setting this.onerror = null first is essential: it prevents an infinite error loop if the placeholder itself is missing. For component-based stacks, bind the same logic in a delegated listener rather than inline markup:

<script>
  document.addEventListener('error', function (event) {
    var el = event.target;
    if (el.tagName === 'IMG' && !el.dataset.fallbackApplied) {
      el.dataset.fallbackApplied = 'true';
      el.src = '/assets/images/placeholder.png';
      // Optional: report the failure to your monitoring endpoint
    }
  }, true);
</script>

A fallback placeholder improves the visual experience but does not replace a correct alt attribute: assistive technology still relies on alt for meaning.

How to write alt text for a meaningful image

A meaningful alt text must describe the specific information or function conveyed by the image rather than offering a generic physical description. Avoid redundant introductory labels such as "image of" or "picture showing," and keep the description to roughly one or two sentences.

Providing clear, concise contextual descriptions allows visually impaired users relying on screen readers to process the document content completely without missing crucial context. Copyright notices, photo credits, and source attributions belong in a visible <figcaption>, not inside alt.

Poor<img src="chart.png" alt="Image of a chart">

Good<img src="chart.png" alt="Q3 revenue chart showing a 15% increase in operational profit">

This finding matters for teams that publish machine-produced visuals at scale; licensing and attribution rules for such assets are covered in this overview of commercial use of AI-generated images, and buyers comparing generation vendors on output rights rather than demo reels can compare them on those terms first.

When to use an empty alt attribute

An empty alt attribute (alt="") should be applied exclusively to purely decorative graphics that convey no functional or factual information. Suppressing decorative descriptions prevents assistive tools from cluttering audio output with unnecessary announcements.

<!-- Decorative divider line ignored by screen readers -->
<img src="divider.svg" alt="" role="presentation">
<!-- Inline decorative SVG is hidden with aria-hidden -->
<svg aria-hidden="true" focusable="false" width="24" height="24"><!-- ... --></svg>

When an img tag includes alt="", screen readers skip the element entirely. Omitting the alt attribute altogether forces screen readers to read out the full raw file path or simply announce "image," creating a confusing user experience. A non-empty description on a decorative graphic is also a documented WCAG failure (F39): eighteen repeated rainbow dividers announced eighteen times add reading time without adding meaning.

Long descriptions for charts, diagrams, and dashboards

Complex visuals such as revenue charts, risk heatmaps, molecular structures, and architecture diagrams cannot be compressed into one or two sentences. The specification-compliant pattern is a short alt summary plus an on-page extended description exposed to everyone, implemented with the native <details> and <summary> elements (no scripting required):

<img src="sales-chart.png"
     alt="Q3 sales chart by region. Full data is available in the expandable description below."
     width="900" height="500">
<h4>Long description</h4>
<details>
  <summary tabindex="0">Text version of the chart data</summary>
  <ul>
    <li>North region: $51,760</li>
    <li>Central region: $28,705</li>
    <li>South region: $15,895</li>
    <li>West region: $7,205</li>
  </ul>
</details>

Adding tabindex="0" to <summary> guarantees keyboard focus, and an <h4> heading above the block creates a landmark that screen reader users can jump to. Sighted users benefit too, since a text table is a fallback when the chart's colour contrast is imperfect.

For interactive charts rendered in <svg> or <canvas>, name the container explicitly and point to the data table:

<figure role="group" aria-labelledby="cls-chart-title" aria-describedby="cls-chart-desc">
  <div id="risk-chart" role="img"
       aria-label="Operational risk exposure by business unit, Q3 2026"></div>
  <figcaption id="cls-chart-title">Operational risk exposure by business unit</figcaption>
  <p id="cls-chart-desc">Full figures are listed in the data table that follows the chart.</p>
</figure>

If a tooltip is genuinely required for sighted users, supply both alt and title with equivalent wording so neither audience loses information:

<img src="heart.png" alt="Favorites" title="Favorites" width="24" height="24">

How to turn an image into a link without losing meaning

To create a functional image link, place the img element inside an <a> tag and set the alt attribute to reflect the destination or operational outcome.

<!-- Correct functional image link -->
<a href="https://example.com/reports/annual-2026.pdf">
  <img src="pdf-download-icon.svg" alt="Download 2026 Annual Financial Report PDF">
</a>
<!-- Graphical submit button -->
<input type="image" src="search-button.png" alt="Search">

When when using an image within a link container that already includes visible link text, the image's alt attribute should be kept empty (alt="") to prevent redundant text reading:

<a href="/favorites">
  <img src="heart.png" alt="">
  Favorites
</a>

Why the title attribute does not replace a text alternative

The title attribute provides optional visual hover tooltips but fails to serve as a reliable text alternative for assistive software. Many screen reader configurations skip title attributes entirely in favor of native alt text.

Furthermore, title attributes do not render on touch devices like smartphones and tablets, where hover interactions do not exist. Relying on title instead of alt leaves mobile and low-vision users without descriptive text when an image fails to load. W3C guidance is explicit: the title attribute must not be used to provide a text alternative for an image, and technique H67 pairs alt="" with no title for decorative graphics.

When an image must be an HTML img tag

An image must be implemented as an HTML img tag whenever it conveys essential information, displays product details, or acts as an interactive link or button. Using native HTML tags guarantees that the media carries accessible text descriptions.

<!-- Semantic content image -->
<img src="product-photo.webp" alt="Ergonomic mesh office chair in black finish"
     width="800" height="800">
<!-- Responsive content image with art direction -->
<picture>
  <source media="(min-width: 1024px)" srcset="chart-wide.webp">
  <img src="chart-narrow.webp" alt="Q3 revenue by region" width="640" height="480">
</picture>

Search engines like Google rely on the img element and its associated alt attribute to parse image context. Utilizing native HTML elements ensures content appears in search results and AI discovery interfaces.

Charts, diagrams, text-bearing graphics, logos used as links, and any image whose removal would change the meaning of the page all belong in semantic markup rather than a stylesheet.

When CSS is the appropriate choice for a graphic

Using CSS background-image is appropriate for non-content visuals, decorative patterns, background overlays, or graphical flourishes. Because CSS background styles carry no alt attribute, they are ignored by screen readers, which is exactly the desired behaviour for decoration. W3C technique C9 explicitly endorses background, background-image, content with ::before/::after, and list-style-image for decorative purposes, while failure F3 forbids using them for information required to understand the page.

/* Decorative background styling */
.hero-banner {
  background-image: url('patterns/abstract-waves.svg');
  background-size: cover;
  background-position: center;
}
/* Decorative icon injected through generated content */
.callout::before {
  content: url('icons/spark.svg');
}

Combining CSS properties like float left or CSS Grid allows developers to lay out decorative elements cleanly without cluttering the primary HTML document structure with non-semantic markup, and keeps the accessibility tree free of noise.