Accessible Images with Craft CMS

Why Craft CMS doesn’t have alt text fields

One of the characteristic features of Craft CMS is its clean-slate approach to content modeling that doesn’t make any assumptions about your content.

In Craft CMS, assets are contained in volumes. Field layouts are attached to volumes, not individual file types. We don’t have a dedicated text alternative field for volumes since there could be different file types in a single volume, and not all image assets require text alternatives.

Developers have a lot of flexibility around how to organize assets and collect any required text alternatives. This post will provide a brief overview about text alternatives, and describe a content model for images that will work for for most sites.

About text alternatives

Text alternatives, also called “alt text”, are text-based equivalents for non-text content, such as images. Text alternatives are exposed to assistive technology, such as screen readers. This enables screen reader users to have access to the images on your website. Text alternatives are a requirement for WCAG 2.1 Success Criterion 1.1.1 Non-text Content. As a bonus, text alternatives can improve your site’s SEO.

For images using img elements, text alternatives should be implemented through the alt attribute.

<img src="dog.jpg" alt="A golden retriever." />

For other imagery, text alternatives can be implemented with the aria-label attribute.

<span class="icon gear" aria-label="Settings"></span>

Writing alternative text can be challenging and takes practice. Not all images require text alternatives, and the same image could have different alternative text depending on its context.

The W3C’s alt decision tree is a fantastic resource for writing appropriate text alternatives for a variety of images.

Content model for accessible images

For most sites, assets uploaded and selected by content authors for front-end display will be informative images: “images that convey a simple concept or information that can be expressed in a short phrase or sentence”. Other types of images, such as decorative images and functional images, will likely have their text alternatives programmed by developers within templates. The configuration described here will work for sites where images uploaded to the CMS require a single text alternative.

1. Create a text alternative field

Navigate to Settings → Fields, click the New field button, and give it the following settings:

Then save the field.

2. Create a volume for images

Navigate to Settings → Assets, click the New volume button, and give it the following settings.

Set a base URL, choose a volume type, and fill out the volume type-specific settings according to your environment.

Drag the newly created “Text alternative” field into a tab in the field layout, and click its gear icon to open the field’s layout settings. Tick the checkbox beside Required and click Apply.

Then save the volume.

3. Create an image field

Navigate to Settings → Fields, click the New Field button, and give it the following settings:

Then save the field.

4. Display the image

Finally, update your templates to display the image with its text alternative. Here’s a Twig snippet that will override the alt attribute on an asset’s generated <img> tag, set to the value of its “Text alternative” field.

{{ asset.img|attr({
    alt: asset.alt,
}) }}