HTML Tutorial / Images: img, Alt Text, and Dimensions

To add an image to an HTML document, put its file URL in the img element's src attribute and describe its relevant content in alt. Set width and height to the image's intrinsic dimensions so the browser can reserve space before the file loads.

Insert an image with img

The img element embeds an image and has no closing tag. Use the lake-and-tree example image to try the following code. Resolve the file address using the relative-path examples in Links: Paths, Page Fragments, and Email.

<img src="html-image-sample-lake-tree-1600-v1.webp"
     alt="A tree on a small island in a lake, with mountains beyond"
     width="1600" height="900">

1. Download the example image and save it beside the HTML file you are editing, such as index.html.
2. Insert the code above inside the HTML file's body and save the file.
3. Open or refresh the HTML file in a browser. You should see the lake photo shown below.

src identifies the file relative to the HTML file's location. The code above looks for the image in the same folder. If you saved it in an images subfolder, change the attribute to src="images/html-image-sample-lake-tree-1600-v1.webp". The filename and extension must also match the actual file.

Clicking the image here opens the original file. Wrapping an image in a link is a separate feature from inserting it with img.

What should alt say?

alt is alternative text. It gives readers who cannot see the image, or whose browser cannot load it, the information the image contributes in context. Describe that role briefly instead of writing “image” or a list of search keywords. For a caption visible to everyone, compare the explanation in Group Images and Captions with figure and figcaption.

<img src="html-image-sample-lake-tree-1600-v1.webp"
     alt="A tree on a small island in a lake, with mountains beyond"
     width="1600" height="900">

If an image is purely decorative and repeats nearby information, an empty alt="" may be appropriate. The empty value identifies it as nonessential; omitting the alt attribute does not convey that intent. If the image conveys essential information, explain it in the alternative text or adjacent prose. The W3C WAI alt-text decision tree helps with ambiguous cases.

What do width and height do?

The example file is 1600×900 pixels. Its width="1600" and height="900" values help the browser calculate the aspect ratio in advance. These attributes do not reduce the image file's byte size or pixel count. Test file-size selection separately from crop changes in Responsive Images: srcset, sizes, and picture.

If the image is wider than the content area, CSS can limit its displayed width while preserving the aspect ratio.

img {
  max-width: 100%;
  height: auto;
}

In a standalone HTML file, put this CSS in a style element in head or a linked stylesheet. The img dimensions describe the file's ratio; CSS controls its current displayed size.

To send a smaller file, you need a separately resized image. The responsive-images tutorial explains how srcset and sizes let the browser choose among image files.

If the image does not appear

• Check the exact filename and extension in src.
• Check the image's folder relative to the HTML file.
• Open the image URL directly in a browser to see whether the file is available.
• Do not assume smaller displayed dimensions mean a smaller downloaded file.

The MDN img element reference describes the available attributes and their behavior.