Prismic alt text not updating? Here's why
Changed the alt text in Prismic's media library and nothing happened on your site? Here's why, how to find every image it affects, and how we fix it.
Alt text is one of those things that gets left until the end. Images go in while the pages are being built, and the alt text is a job for “later”. So at some point someone opens the media library, works through every image and writes proper alt text for all of them. Then they check the site, and nothing has changed.
It's not a bug, and you didn't do it wrong. It's how Prismic stores images.
The media library is a starting point, not the source
When you pick an image in a document, Prismic copies the image's URL, its dimensions and its alt text into that document. From then on the document has its own copy. Your site reads the document, so it gets the document's alt text, not the library's.
That means:
- Alt text you add in the media library is used the next time someone picks that image
- It doesn't reach documents that already use the image
- Editing the alt text in a document doesn't change the library either
Prismic's own team confirmed this on their forum: changing the alt text in the media library “doesn't apply automatically to Images inside the documents”, and the advice was to remove and re-add the images. Storyblok works the same way, their team calls the library value “only a template”.
There's a reason for it. The same photo can need different alt text in different places: a team photo is “Our team at the 2024 offsite” on the about page and “Three people around a laptop” on a blog post about remote work. A copy per document allows that. It also means a library-wide fix does nothing for pages that already exist.
From experience, almost nobody adds alt text when they upload. It's easy to forget, and the upload screen doesn't ask. So being able to fix it afterwards, and have it reach your pages, is exactly what you want, and it's the one thing Prismic doesn't do.
Find every image where the alt text never made it
The hard part isn't the fix, it's knowing where. Prismic can't tell you which documents use an image, or which of them are missing alt text the library has. That's what we built Cojack for.
- Paste your site's URL into Cojack and add your write token (Settings → Content model access), so it can read the media library
- Resync with Media library switched on
- Open Assets and click the Alt only in library card
- Every image there has alt text in the library that never reached the page. Click Used in to see the documents, each image shows the library's alt text next to it
The Missing alt text card next to it lists every image with no alt text at all, library or not.
Find the images where your alt text never landed
Paste your URL. Cojack reads your whole repository and the media library, and shows every image whose alt text is in the library but not on your pages.
The fixes, in the order we do them
- 1
Start with the pages people see most
Your homepage, the main landing pages and anything in a shared slice or layout. One image in a header or footer can be on every page.
- 2
Edit the alt text in the document
Open the document, click the image, change the alt text in the image field and publish. You don't have to remove and re-add the image. [check: does re-picking reset crops?]
- 3
Check your releases
A document waiting in a release has its own copy too. Fix it there, or it'll put the old alt text back when the release goes live.
- 4
Do every language
Each locale is its own document with its own alt text. The media library only has one alt text per image, so translated pages always need doing by hand.
- 5
For a lot of images, sync it
On bigger sites we don't do this by hand. We run our own sync: it reads the alt text from the media library and writes it into every image field that has none, through Prismic's Migration API.
It only fills empty ones, so alt text someone wrote for a specific page stays as it is.
How we set up new projects so it doesn't happen
- Alt text at upload. When we hand a site over, the one rule we give editors is: write the alt text in the media library when you upload, before the image goes on a page.
- A check before launch. We run the site through Cojack before it goes live, and the missing alt text check is on the list.
- Decorative images get empty alt on purpose. Background textures and divider graphics shouldn't be read out, so we make those slice backgrounds rather than image fields that look like they're missing something. [check]
What happened on a client site
We noticed one of our client sites had a lot of images without alt text, so we went to fix it properly. We wrote a script that went through the whole media library and set alt text on every image. The media library looked great.
Then Cojack still flagged the same images. We assumed it was a bug in Cojack, it wasn't. The library had the alt text, the pages didn't. The script had fixed the template, and every page still had its old, empty copy.
Two things we took from it:
- Fix the pages, not just the library. Our sync now writes the alt text into the documents as well, and only where they're empty.
- Show both. Cojack now reads the media library too, and shows the library's alt text next to any image that's missing it on the page. That's where the Alt only in library card comes from.
Quick answers
QWhy doesn't Prismic just update every page?
Because each document has its own copy of the alt text, so a page can have alt text that fits that page. The downside is that a library-wide fix doesn't reach existing pages.
QDoes my site read alt text from the media library?
No. Your site gets the alt text from the document, through the API. Unless your code fetches the media library separately, the library's alt text never reaches your pages.
QIs it the same in Storyblok?
Yes. Storyblok copies the alt text into the asset field when you pick the image, and changing it in the asset library doesn't update stories that already use it.
QShould every image have alt text?
Every image that means something, yes. Purely decorative images should have empty alt text, so screen readers skip them. Cojack flags those too, so you'll see them in the list. That's fine, as long as it's on purpose.
To check every image on your site, not just these, see how to find every image missing alt text.
QIs there a length limit?
Yes, 500 characters in the media library. Longer alt text fails to save, but the screen can look like it worked until you reload. You rarely need more than a sentence anyway.
