Wagtail generally puts developers in control of content modeling and front-end markup, but there are a few areas to be aware of nonetheless, and ways to help authors be aware of readability best practices. Note there is much more to building accessible websites than we cover here – see our list of accessibility resources for more information.
As part of defining your site’s models, here are areas to pay special attention to:
Alt text for images¶
The default behavior for Wagtail images is to use the
title field as the alt text (#4945).
This is inappropriate, as it’s not communicated in the CMS interface, and the image upload form uses the image’s filename as the title by default.
Ideally, always add an optional “alt text” field wherever an image is used, alongside the image field:
- For normal fields, add an alt text field to your image’s panel.
- For StreamField, add an extra field to your image block.
- For rich text – Wagtail already makes it possible to customize alt text for rich text images. Unfortunately, it’s not currently possible to set alt text as an optional field in these situations (see #6494).
When defining the alt text fields, make sure they are optional so editors can choose to not write any alt text for decorative images. Take the time to provide
help_text with appropriate guidance.
For example, linking to established resources on alt text.
Should I add an alt text field on the Image model for my site?
It’s better than nothing to have a dedicated alt field on the Image model (#5789), and may be appropriate for some websites, but we recommend to have it inline with the content because ideally alt text should be written for the context the image is used in:
- If the alt text’s content is already part of the rest of the page, ideally the image should not repeat the same content.
- Ideally, the alt text should be written based on the context the image is displayed in.
- An image might be decorative in some cases but not in others. For example, thumbnails in page listings can often be considered decorative.
See RFC 51: Contextual alt text for a long-term solution to this problem.
Missing embed titles are common failures in accessibility audits of Wagtail websites. In some cases, Wagtail embeds’ iframe doesn’t have a
title attribute set. This is generally a problem with OEmbed providers like YouTube (#5982).
This is very problematic for screen reader users, who rely on the title to understand what the embed is, and whether to interact with it or not.
If your website relies on embeds that have are missing titles, make sure to either:
- Add the OEmbed title field as a
- Add a custom mandatory Title field to your embeds, and add it as the
Available heading levels¶
Wagtail makes it very easy for developers to control which heading levels should be available for any given content, via rich text features or custom StreamField blocks. In both cases, take the time to restrict what heading levels are available so the pages’ document outline is more likely to be logical and sequential. Consider using the following restrictions:
h1in rich text. There should only be one
h1tag per page, which generally maps to the page’s
- Limit heading levels to
h2for the main content of a page. Add
h3only if deemed necessary. Avoid other levels as a general rule.
- For content that is displayed in a specific section of the page, limit heading levels to those directly below the section’s main heading.
If managing headings via StreamField, make sure to apply the same restrictions there.
Bold and italic formatting in rich text¶
By default, Wagtail stores its bold formatting as a
b tag, and italic as
i (#4665). While those tags don’t necessarily always have correct semantics (
em are more ubiquitous), there isn’t much consequence for screen reader users, as by default screen readers do not announce content differently based on emphasis.
If this is a concern to you, you can change which tags are used when saving content with rich text format converters. In the future, rich text rewrite handlers should also support this being done without altering the storage format (#4223).
Accessibility in templates¶
Here are common gotchas to be aware of to make the site’s templates as accessible as possible,
Alt text in templates¶
See the content modelling section above. Additionally, make sure to customise images’ alt text, either setting it to the relevant field, or to an empty string for decorative images, or images where the alt text would be a repeat of other content. Even when your images have alt text coming directly from the image model, you still need to decide whether there should be alt text for the particular context the image is used in. For example, avoid alt text in listings where the alt text just repeats the listing items’ title.
wagtailforms Form builder uses Django’s forms API, but make sure to go beyond Django’s default forms rendering:
- Avoid rendering helpers such as
as_p, which can make forms harder to navigate for screen reader users or cause HTML validation issues (see Django ticket #32339).
- Make sure to visually distinguish required and optional fields.
- If relevant, for larger forms take the time to group related fields together in
fieldset, with an appropriate
- If relevant, use the appropriate
- Make sure to display an example value, or the expected format, for fields that accept arbitrary values but have validation – like Date and Date/Time (see Django ticket #32340).
There are further issues with Django’s built-in forms rendering (such as #32338) – make sure to test your forms’ implementation and review official W3C guidance on accessible forms development for further information.
We focus on considerations specific to Wagtail websites, but there is much more to accessibility. Here are valuable resources to learn more, for developers but also designers and authors: