Skip to content
Kuza Ndoto Academy

Images

BeginnerChapter 2 · Page 9 of 255 min readUpdated 15 Nov 2026

Images make pages more engaging and often carry real information: a product photo, a chart, a map. The <img> element embeds an image, and its attributes control where the file comes from, what it means for people who can't see it, and how it loads on slow connections and small screens.

The img element

<img src="images/mt-kenya.jpg" alt="Snow on the peaks of Mount Kenya at sunrise" width="800" height="533">
  • src (source) is the image's URL, absolute or relative, just like a link's href.
  • alt is the text alternative, explained below.
  • width and height give the image's size in pixels, written as plain numbers without "px".

<img> is a void element, so it has no closing tag. It is also an inline element: it sits in the line of text like a large letter unless CSS changes that.

Alt text: the most important attribute

The alt attribute describes the image for anyone who can't see it:

  • Screen-reader users hear the alt text read aloud.
  • If the image fails to load (a broken link or a weak connection), the browser shows the alt text in its place.
  • Search engines use it to understand what the image shows.
alt="Students planting trees in Nyeri" Screen reader reads the alt text "Students planting trees in Nyeri, image" If the image cannot load, the browser shows the same alt text in its place.
Figure 1. For many users the alt text is the image. Exactly how it is announced varies between screen readers.

Writing good alt text

  • Describe the purpose, briefly. Ask: if I replaced this image with text, what would I write? Usually one short sentence is enough.
  • Don't start with "image of" or "picture of". Screen readers already announce that it is an image.
  • For a linked image, describe where the link goes: a logo linking home could have alt="Kuza Ndoto home".
  • For an image containing text, such as a poster, include that text in the alt.
  • For purely decorative images (a swirl, a background flourish), use an empty value: alt="". Screen readers then skip the image entirely. Never leave alt out completely, because some screen readers will read the file name instead, such as "IMG underscore 2041 dot JPG".

Width, height and layout shift

Images often load after the text. If the browser doesn't know an image's size, it reserves no space, then pushes the text down when the image arrives. Content jumping around while you read is called layout shift, and it is annoying, especially on phones. Setting width and height lets the browser calculate the image's shape (its aspect ratio) and reserve the right space from the start. CSS can still make the image smaller or flexible; the browser keeps the proportions.

Lazy loading and file formats

Add loading="lazy" to images further down the page. The browser then waits to download them until the user scrolls near them, which saves data and speeds up the first view:

<img src="images/team.jpg" alt="Our eight volunteers at the Kibera library" width="600" height="400" loading="lazy">

Don't lazy-load the main image at the top of the page; it should load straight away.

FormatBest for
JPEG (.jpg)Photos
PNG (.png)Screenshots and graphics with sharp edges or transparency
SVG (.svg)Logos and icons; vector drawings that stay sharp at any size
WebP / AVIFModern formats giving much smaller files for photos and graphics

Captions and responsive images

To give an image a visible caption, wrap it in <figure> with a <figcaption>. The caption is linked to the image for assistive technology, and the alt text still describes the image itself.

<figure>
  <img src="images/sgr.jpg" alt="Madaraka Express train at Mombasa terminus" width="800" height="450">
  <figcaption>The SGR cut the Nairobi–Mombasa journey to about five hours.</figcaption>
</figure>

Phones don't need huge desktop images. With srcset you list several sizes of the same picture and the browser downloads the most suitable one for the screen. sizes tells it how wide the image will be displayed:

<img src="images/market-800.jpg"
     srcset="images/market-400.jpg 400w, images/market-800.jpg 800w, images/market-1600.jpg 1600w"
     sizes="(max-width: 600px) 100vw, 600px"
     alt="Fruit stalls at Owino market in Kampala" width="800" height="533">

Here 400w means "this file is 400 pixels wide". The sizes value says: on screens up to 600px wide, the image fills the whole viewport width; otherwise it is shown 600px wide. A phone may pick the 400px file and save most of the data. When you need different formats or crops, the <picture> element with <source> children does a similar job.

Try it

The first image's src is a data URL, a tiny drawing written as text, so the example works without a separate file. In your projects, src will be a file path such as images/photo.jpg. The second image points to a file that doesn't exist.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Images</title>
  </head>
  <body>
    <h1>Images and alt text</h1>
    <figure>
      <img src="data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20300%20150'%3E%3Crect%20width='300'%20height='150'%20fill='%2387ceeb'/%3E%3Cpath%20d='M0%20150L120%2040L200%20120L240%2090L300%20150Z'%20fill='%23345'/%3E%3C/svg%3E"
           alt="Simple drawing of dark mountains under a blue sky" width="300" height="150">
      <figcaption>A drawing that loads correctly.</figcaption>
    </figure>
    <figure>
      <img src="missing-photo.jpg" alt="Students planting trees in Nyeri" width="300" height="150">
      <figcaption>This file is missing, so you see its alt text.</figcaption>
    </figure>
  </body>
</html>

The first figure shows mountains under a blue sky. In the second, the browser shows the alt text "Students planting trees in Nyeri" (often with a small broken-image icon) inside a 300 × 150 space reserved by the width and height.

Key points

  • <img src="…" alt="…"> embeds an image; it is a void, inline element.
  • Alt text should briefly convey the image's purpose; decorative images get alt="", never a missing alt.
  • Set width and height to prevent layout shift; use loading="lazy" for images lower down.
  • <figure> and <figcaption> add captions; srcset and sizes serve smaller files to small screens.
Up next · Text & ContentListsOrdered, unordered and description lists.
→

Tip: use the ← and → keys to move between pages.