Wagtail Accessibility Checklist 2026 | WCAG 2.1 AA & EAA Compliance

Wagtail's StreamField is the editorial superpower of the CMS — content editors compose pages from reusable blocks (Hero, Card Grid, Quote, CTA). Developers building those blocks frequently emit divs and spans rather than semantic header, article, section, blockquote, and figure elements. The resulting front-end HTML looks fine to sighted users but screen-reader rotor navigation has no landmarks and the page reading order is opaque. The pattern fails WCAG 1.3.1 Info and Relationships because the visual structure is not programmatically determinable.

{# blocks/hero_block.html #}
<div class="hero">
  <div class="hero-heading">{{ value.heading }}</div>
  <div class="hero-body">{{ value.body }}</div>
</div>

{# blocks/hero_block.html #}
<section class="hero" aria-labelledby="hero-{{ value.id }}">
  <h1 id="hero-{{ value.id }}">{{ value.heading }}</h1>
  <div class="hero-body">{{ value.body|richtext }}</div>
</section>

Wagtail's `{% image %}` template tag renders responsive image renditions but uses the image's `default_alt_text` field, which is optional and frequently left blank by content editors uploading from a phone or via bulk import. When the field is blank, the rendered `<img>` element gets `alt=""` which signals 'decorative' to screen readers. Informative product photos, staff portraits, and infographics then disappear from the screen-reader experience entirely.

{# Wagtail image tag without explicit alt #}
{% image page.hero_image fill-1200x600 %}
{# Renders: <img src='...' alt=''> if default_alt_text is blank #}

{# Pass alt explicitly when image is informative #}
{% image page.hero_image fill-1200x600 alt=page.hero_image_alt %}
{# In settings.py #}
WAGTAIL_REQUIRE_IMAGE_ALT_TEXT = True

Wagtail Localize (the official multi-language extension) renders a language switcher dropdown that lists each available translation as a link with the language name in English ('French', 'German', 'Welsh'). Screen readers reading the switcher list announce the names in the page's language, which is wrong — 'French' should be announced with English pronunciation but 'Français' (in the switcher) should be announced as French. Most importantly, the switcher links themselves lack a `lang` attribute pointing at the target language, so assistive tech cannot pre-announce the language change.

{# Default switcher #}
<ul>
  {% for translation in translations %}
    <li><a href="{{ translation.url }}">{{ translation.language_name_local }}</a></li>
  {% endfor %}
</ul>

{# Accessible switcher #}
<ul>
  {% for translation in translations %}
    <li>
      <a href="{{ translation.url }}" lang="{{ translation.locale.language_code }}" hreflang="{{ translation.locale.language_code }}">
        {{ translation.language_name_local }}
      </a>
    </li>
  {% endfor %}
</ul>

Draftail (Wagtail's rich-text editor) exposes heading levels H2-H5 in its toolbar. Editors trying to make a single line stand out visually frequently apply H3 or H4 styling to that line, even when it is not a section heading. The rendered page then contains phantom headings that break screen-reader heading navigation: users pressing 'H' to jump to the next section land on a one-line emphasis instead of the next real section.

# settings.py
WAGTAILADMIN_RICH_TEXT_EDITORS = {
    'default': {
        'WIDGET': 'wagtail.admin.rich_text.DraftailRichTextArea',
        'OPTIONS': {
            'features': ['h2', 'h3', 'h4', 'h5', 'bold', 'italic', 'link']
        }
    }
}

# settings.py - restrict to h2 + h3 only
WAGTAILADMIN_RICH_TEXT_EDITORS = {
    'default': {
        'WIDGET': 'wagtail.admin.rich_text.DraftailRichTextArea',
        'OPTIONS': {
            'features': ['h2', 'h3', 'bold', 'italic', 'link', 'ol', 'ul']
        }
    }
}
# Add a callout block-style instead of fake headings

Wagtail's built-in form builder (the `AbstractEmailForm` and `WagtailCaptchaEmailForm` classes) renders form fields via the default Django form widget, which emits `<input>` elements with `required` but no `aria-required` and no visual indication of required status beyond an asterisk in the label that may or may not be announced. The form also surfaces validation errors as a list above the form rather than associated with each field via `aria-describedby`.

{# Default Wagtail form rendering #}
{{ form.as_p }}
{# Renders inputs without aria-required, errors above form, no focus management #}

{# Custom accessible form template #}
<form method="post" novalidate>
  {% csrf_token %}
  {% for field in form %}
    <div class="field">
      <label for="{{ field.id_for_label }}">
        {{ field.label }}
        {% if field.field.required %}<abbr title="required">*</abbr>{% endif %}
      </label>
      {{ field|add_attrs:'aria-required:true,aria-invalid:false' }}
      {% if field.errors %}
        <div id="{{ field.name }}-error" role="alert" class="error">{{ field.errors|first }}</div>
      {% endif %}
    </div>
  {% endfor %}
  <button type="submit">Submit</button>
</form>

The Wagtail admin page-explorer tree supports drag-and-drop reordering of child pages via the mouse. The drag-handle is rendered as a visual icon with no keyboard equivalent in the default theme. Editors who cannot use a mouse — including some screen reader users and people with motor impairments — cannot reorder pages without resorting to the 'Move' menu option, which is two clicks deeper and not always discoverable. The pattern is improving in Wagtail 6.x but custom admin customisations frequently regress it.

{# wagtail_hooks.py custom sortable #}
class CustomChooserAdmin(...):
    sortable = True
    # Drag-only, no keyboard equivalent

{# Use Wagtail 6.0+ accessible_sortable mixin #}
from wagtail.admin.viewsets.mixins import AccessibleSortableMixin

class CustomChooserAdmin(AccessibleSortableMixin, ...):
    sortable = True
    # Adds Move up / Move down buttons + drag-and-drop

Developers building Wagtail templates frequently style anchor (`<a>`) elements as buttons for visual consistency and add `role='button'` to communicate the semantic intent. This works for some assistive technology but breaks expected keyboard behaviour: anchors activate on Enter only, buttons activate on Enter AND Space. Screen-reader users pressing Space on the styled anchor scroll the page instead of activating the button.

{# Anchor styled as button with role override #}
<a href="#" class="btn btn-primary" role="button" onclick="openModal()">Sign up</a>

{# Real button element for action triggers #}
<button type="button" class="btn btn-primary" onclick="openModal()">Sign up</button>

{# Anchor for navigation (no role override) #}
<a href="/signup/" class="btn btn-primary">Sign up</a>

Wagtail's built-in search (using `wagtail.search.backends.database` or Elasticsearch) renders a results page with the query, the result count, and a paginated list. The result count is rendered in plain text without an `aria-live` region. Screen reader users who change pagination or refine the query via the URL parameters do not get an announcement that the result count changed — they have to navigate back to the top of the page to find it.

{# search_results.html #}
<h1>Search results for "{{ search_query }}"</h1>
<p>{{ search_results.paginator.count }} results found</p>

{# search_results.html #}
<h1>Search results for "{{ search_query }}"</h1>
<div role="status" aria-live="polite" aria-atomic="true">
  <p>{{ search_results.paginator.count }} results found</p>
</div>