How to Fix Image Alt Text
Give every picture on your site a written description, so a screen reader can read it aloud to a visitor who cannot see it and a search engine can tell what the picture shows.
Read this first: each file has one description, and a widget's Image field uses it unless someone has set a different one there. Two cases must be fixed on the page itself: a picture inside a block of text, and any picture set to Custom. Step 4 covers both.
Step-by-Step Instructions
1. Open the Description Box
- Navigate: Click Images & Docs in the menu bar.
- Find the Picture: Narrow the grid with the Folder dropdown, or type a word into Search.
- Open the Menu: Click the ▾ on the picture's tile and choose Edit Alt Text.
- For a batch, tick each picture first, then open Mass Edit and choose Edit Alt Text. It is the same screen, with one row per picture.
- ⚠️ You can select up to 100 pictures at a time. If you tick more, the extra ones are unticked for you, and the platform chooses which 100 stay ticked.
- Documents have no description to set, so a PDF, a Word file or an SVG logo has no Edit Alt Text on its menu.
2. Write the Description
Type into the Alt Text box on each row. Say what is in the picture, in the words a guest would use: King suite bedroom with harbour view, not IMG_4471 and not hotel photo.
- Length
- 250 characters. A sentence is plenty.
- Punctuation
- No apostrophes and no quotation marks. The box rejects both. Write the terrace at the hotel, not the hotel's terrace.
- Repeats
- Give each picture its own description. When the screen opens, it lists any description used on more than one picture. Repeated descriptions count against you in an accessibility audit.
- Rows are listed alphabetically by file name, not in the order you ticked them. Read the file name on each row before typing.
3. Save
- Click Save: One click saves every row you changed.
- Check One: Open a picture's ▾ menu and choose Details to see the description now saved with the file.
4. Fix the Placements a Library Description Does Not Reach
- List them: On the picture's ▾ menu choose View Where it's Used. Each row is one place the picture appears, and the Location column names the widget holding it. See How to Check What Uses an Image.
- Open each widget: Click Edit on the row to open that widget.
- Check the choice on the Image field: Use Global takes the description you just wrote. Custom keeps a description written for that one placement, and your library edit does not touch it. Switch to Use Global unless the picture really means something different in that place.
- Handle text blocks separately: A row whose Location says Text is a picture placed inside a block of text. Its description is stored in the text itself, and you set it on the HTML tab of the text editor. See How to Use the Text Editor.
- Save and Publish: Save each widget you changed, then publish the pages. See How to Publish Your Site.
Pro-Tips & Troubleshooting
- The description I typed is not on the live page. That placement is set to Custom, or the picture sits inside a block of text. Step 4 covers both.
- The box will not accept my text. There is an apostrophe or a quotation mark in it. Rewrite the sentence without them.
- The screen listed some of my descriptions when it opened. Those descriptions are used on more than one picture. Give each one its own.
- I ticked 150 pictures and got 100 rows. That is the selection limit. Work through the folder in batches.
- A logo or a PDF has no Edit Alt Text. Descriptions are for images. SVG files count as documents here, so a logo saved as SVG has none.
- Searching the library got harder after I edited. The Search box on Images & Docs matches the description as well as the file name, so changing a description changes what finds it. Keep the words a colleague would search for in the sentence.
- Start with the pictures that are on a page. A description on a file nobody has placed changes nothing for a visitor. Work through the pages first, then tidy the rest of the library.
→ Next: How to Check What Uses an Image — find every page a picture appears on, so you can finish the job
Related: How to Fill In a Widget — the Image field and its description choice · How to Upload Images — getting pictures into the library · How to Use the Text Editor — pictures placed inside text