# Image alt text: how to write it with examples

> Choose alt text for product photos, image links, decoration and charts, with HTML examples and complete text alternatives.


**Alt text communicates the information or function an image contributes in context.** In HTML, it is commonly written in the `alt` attribute of an `img` element. It helps someone who cannot see the image understand its contribution. Start by deciding what the person needs to know or do at that point in the page.

## One image can need different alternatives

Imagine a photograph of a blue mug with a large handle. These fictional examples show how its alternative changes with its role:

| Context | Proposed alternative | Reason |
|---|---|---|
| Product photograph where appearance matters | `Blue mug with a large handle and matte finish` | Describes relevant visible characteristics |
| Image is the only link to the product | `View the blue ceramic mug` | Communicates the link destination |
| Repeated decoration beside an equivalent description | `alt=""` | Avoids repeating information already available |

The [W3C/WAI decision tree](https://www.w3.org/WAI/tutorials/images/decision-tree/) organizes these choices around information, function and redundancy. A decorative image keeps an empty attribute. Leaving the attribute out entirely does not communicate the same decision and may cause assistive technology to announce the filename.

## How to write the HTML

```html
<img src="blue-mug.webp"
 alt="Blue mug with a large handle and matte finish" />
```

The filename locates the image; the alternative serves the reader. `IMG_4832.webp` does not explain what is visible. “Best cheap mug sale gift blue mug” adds a commercial keyword list without describing the photograph. If the product has a stated capacity that appears only in its specification, keep that as product information rather than guessing it from the image.

WAI distinguishes [informative images](https://www.w3.org/WAI/tutorials/images/informative/) and [functional images](https://www.w3.org/WAI/tutorials/images/functional/). For a magnifying-glass icon that is the sole content of a search button, the alternative should communicate “Search.” Describing a circle and diagonal line leaves the action unexplained. Where the button already has an equivalent accessible name, avoid unnecessary duplication.

## Images containing text or charts

If a poster contains a date and venue unavailable elsewhere, that information needs a text alternative. When it contains substantial information, also publish it as nearby real text. Readers can then select, read and use it without depending on the poster.

A chart needs more than “results chart.” In a hypothetical example, it might compare 12 bookings in April with 18 in May. A brief alt can introduce the comparison while a nearby table preserves both values, the unit and period. Describe what the data shows. Do not attribute the change to a campaign when the chart does not establish that cause.

## Check the published result

Read the page as though its images were absent. Can you understand the product, link destination and chart information? Then inspect the live HTML. Some editors save a description without emitting an `alt` attribute. For links and buttons, check the full accessible name for repetition too.

Google uses context and alternatives to understand images, as its [Google Images recommendations](https://developers.google.com/search/docs/appearance/google-images) explain. That does not make alt text a place for keyword stuffing or guarantee rankings. The task is complete when someone can understand or use the image in that particular page.

## Plan your next post in HeyMark.

Keep the idea, review the draft with your team, and see how it performed in the accounts you connected.

[Start free](https://app.heymark.ai) · [See how it works](https://heymark.ai/en/#product)

## Developer and agent resources

- [HeyMark MCP documentation](https://heymark.ai/en/mcp/)
- [llms.txt](https://heymark.ai/llms.txt)
- [Full site content for language models](https://heymark.ai/llms-full.txt)
- MCP protocol endpoint: `POST https://mcp.heymark.ai`
- OAuth protected-resource metadata: [/.well-known/oauth-protected-resource](https://mcp.heymark.ai/.well-known/oauth-protected-resource)
- MCP server card: [/server-card](https://mcp.heymark.ai/server-card)
