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 SettingsFields, click the New field button, and give it the following settings:

NameText alternative
Default InstructionsA short description of the image.
Field Limit150 Characters

Then save the field.

It is possible to use the default title field to store text alternatives, but it’s a good idea to create a dedicated field. The title field automatically populates with the file name, so content authors might not notice if it needs to be updated.

2. Create a volume for images #

Navigate to SettingsAssets, click the New volume button, and give it the following settings.

Assets in this volume have public URLsYes

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 SettingsFields, click the New Field button, and give it the following settings:

Field TypeAssets
Restrict allowed file typesYes – “Image”
Validate related assetsYes

Then save the field.

Checking Validate related assets ensures that entries won’t be published if they contain images with no text alternatives.

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,
}) }}
Five Accessibility Facts for GAAD 2021
Accessibility Home
CKEditor Plugin Released