Sanity images missing alt text: fix an accessibility audit fail
By Nayan Kyada · · 6 min read
Part of The Sanity + Next.js Guide
An accessibility audit, a lawyer's letter, or a Lighthouse report has told you your Sanity-powered site has images with missing alt text. It is usually a bigger problem than a handful of pages, because the cause sits in the schema and the front-end component, not in what editors typed. This post covers how to find every gap, how to stop new ones, and what to ask a developer to do.
Why Sanity images end up with no alt text
A plain Sanity image field stores the asset reference and the hotspot and crop data. It does not store a description. If the original developer never added an alt field to the schema, editors had nowhere to write one.
There are three common situations I find on inherited sites:
- The schema has no alt field at all, so every image renders with no description.
- The schema has an alt field, but it is optional, so editors skip it under deadline.
- The schema and content are fine, but the GROQ projection never fetches alt, or the React component never passes it to the image element.
The third one is the most annoying, because editors did the work and it never reached the page. Check it first, since it costs the least to fix.
What it costs to ignore
Missing alt text is not only a compliance concern. Screen reader users get nothing from those images. Image search has less context for ranking them. Several markets now have accessibility regulations that apply to commercial sites, and a vague audit finding turns into a formal request faster than most owners expect. I am not a lawyer, so treat this as a reason to look, not legal advice.
The cost also grows with content. Every new article published into a broken schema adds more images to fix by hand later.
Step 1: measure the gap with GROQ
Open the Vision tool in Studio and count the damage per document type. For a top-level image field:
*[_type == "post" && defined(mainImage.asset) && (!defined(mainImage.alt) || mainImage.alt == "")]{
_id,
title,
"slug": slug.current
}Repeat for each document type that has an image. Then do the harder part: images inside Portable Text bodies and page builder blocks. Those live in arrays, so you need a query per block type, or a small script that walks documents and reports any image object with an asset and no alt. A script that exports to CSV is also the right deliverable to hand to editors, because they can fix pages in priority order.
Be honest about the result. If thousands of images lack alt text, nobody is going to hand-write all of it this week. Prioritise by traffic: homepage, top landing pages, and the most visited articles first.
Step 2: enforce alt in the schema
Making the field required for every image is tempting but wrong, because decorative images should have no description. The better pattern is a required alt field with an explicit decorative escape hatch.
// schemaTypes/objects/accessibleImage.ts
import {defineField, defineType} from 'sanity'
export const accessibleImage = defineType({
name: 'accessibleImage',
title: 'Image',
type: 'image',
options: {hotspot: true},
fields: [
defineField({
name: 'decorative',
title: 'Decorative image (no description needed)',
type: 'boolean',
initialValue: false,
}),
defineField({
name: 'alt',
title: 'Alt text',
type: 'string',
description: 'Describe what the image shows, as you would to someone on the phone.',
hidden: ({parent}) => Boolean(parent?.decorative),
validation: (Rule) =>
Rule.custom((value, context) => {
const parent = context.parent as {asset?: unknown; decorative?: boolean} | undefined
if (parent?.asset && !parent.decorative && !value) {
return 'Add alt text, or mark the image as decorative.'
}
return true
}),
}),
],
})Then replace the raw image type with accessibleImage across documents and blocks. Existing content will show validation warnings in Studio, which doubles as a to-do list for editors. If you want a refresher on how rules like this behave, my custom validation rules guide covers the details. Changing a field type on a live dataset has its own risks, so read restructuring a Sanity schema on a live site before touching production.
Step 3: make sure alt reaches the page
Fetch both fields in the query, then render them correctly in the component.
// components/SanityImage.tsx
import Image from 'next/image'
import {urlFor} from '@/sanity/lib/image'
type Props = {
image: {
asset?: {_ref: string}
alt?: string
decorative?: boolean
}
width: number
height: number
sizes?: string
priority?: boolean
}
export function SanityImage({image, width, height, sizes, priority}: Props) {
if (!image?.asset) return null
const alt = image.decorative ? '' : (image.alt ?? '')
return (
<Image
src={urlFor(image).width(width).height(height).url()}
alt={alt}
width={width}
height={height}
sizes={sizes}
priority={priority}
/>
)
}Your projection must include alt and decorative on every image, including those nested in blocks. This is the step teams forget when they add a field later. If you use typed queries, Sanity TypeGen will flag the missing property at build time instead of in an audit.
One more place to check is Portable Text. Inline images in article bodies are rendered by a custom component, and that component often ignores alt. My Portable Text components walkthrough shows where to wire it in.
Step 4: verify
- Re-run the GROQ gap queries and confirm the count falls as editors work through the list.
- Crawl the live site with an accessibility checker, such as Lighthouse or axe, and filter for image alt findings.
- View source on a few key pages and confirm the alt attribute is present, with an empty value only on genuinely decorative images.
- Publish a test document without alt and confirm Studio blocks or warns on it.
Automated tools only catch missing alt, not bad alt. "image123.jpg" passes the check and helps nobody, so spot-check quality on your top pages by hand.
What to ask a developer
- Will you add the alt field and decorative toggle to every image type, including blocks and Portable Text?
- How will you deal with the existing images: a CSV export for editors, a bulk script, or both?
- Do you update the GROQ projections and components, or only the schema?
- How do you stop it from regressing, for example with validation and typed queries?
- Can you scope this alongside the wider findings, since alt text rarely comes alone?
If editors resist the extra field, the problem may be wider than alt text. I covered that in why editors avoid Sanity Studio.
This is work I do. A Performance & Sanity audit, from $800, covers schema, queries, and front-end output, and alt text coverage is part of what I check.
Frequently asked questions
01Why do my Sanity images have no alt text?
Sanity image fields do not include an alt field by default. Unless the schema adds one and the GROQ query fetches it, the front end renders images with an empty or missing alt attribute.
02How do I find Sanity images without alt text?
Run a GROQ query per document type that filters on images where the asset is defined but alt is missing or empty. Images inside Portable Text and page builder blocks need their own queries.
03Should decorative images have alt text?
No. Purely decorative images should render an empty alt attribute so screen readers skip them. Give editors an explicit decorative toggle instead of letting them leave alt blank by accident.