Accessibility Guides for cognitive

Why This Matters

The autocomplete attribute does more than enable browser autofill — it programmatically communicates the purpose of a form field to assistive technologies. This information is critical for several groups of users:

• Screen reader users rely on the announced field purpose to understand what information is being requested. Without a valid autocomplete value, the screen reader may not convey this context clearly.
• Users with cognitive disabilities benefit from browsers and assistive tools that can auto-populate fields or display familiar icons based on the field’s purpose, reducing the mental effort required to complete forms.
• Users with mobility impairments benefit from autofill functionality that minimizes the amount of manual input required.
• Users with low vision may use personalized stylesheets or browser extensions that adapt the presentation of form fields based on their declared purpose (e.g., showing a phone icon next to a telephone field).

This rule maps to WCAG 2.1 Success Criterion 1.3.5: Identify Input Purpose (Level AA), which requires that the purpose of input fields collecting user information can be programmatically determined. The autocomplete attribute is the standard mechanism for satisfying this requirement in HTML.

How the Rule Works

The axe rule autocomplete-valid checks that:

1. The autocomplete attribute value is a valid token (or combination of tokens) as defined in the HTML specification for autofill.
2. The value is appropriate for the type of form control it is applied to (e.g., email is used on an email-type input, not on a checkbox).
3. The tokens are correctly ordered when multiple tokens are used (e.g., a section name followed by a hint token followed by the field name).

The rule flags fields where the autocomplete value is misspelled, uses a non-existent token, or is applied in an invalid way.

How to Fix It

1. Identify all form fields that collect personal user information (name, email, address, phone number, etc.).
2. Check if the data type matches one of the 53 input purposes defined in WCAG 2.1 Section 7.
3. Add the correct autocomplete value to each matching field. Make sure:
   • The value is spelled correctly.
   • It is appropriate for the input type.
   • If using multiple tokens, they follow the correct order: optional section name (section-*), optional shipping or billing, optional home, work, mobile, fax, or pager, and then the autofill field name.
4. Set autocomplete="off" only when you have a legitimate reason to disable autofill — and note that this does not exempt you from the rule if the field still collects identifiable user data.

Common autocomplete Values

Here are some of the most frequently used values:

Examples

Incorrect: Missing or Invalid autocomplete Values

<!-- Missing autocomplete attribute entirely -->

<label for="name">Full Name</label>
<input type="text" id="name" name="name">

<!-- Misspelled autocomplete value -->

<label for="email">Email</label>
<input type="email" id="email" name="email" autocomplete="emal">

<!-- Invalid autocomplete value -->

<label for="phone">Phone</label>
<input type="tel" id="phone" name="phone" autocomplete="phone-number">

In the examples above, the first field has no autocomplete attribute, the second has a typo (emal instead of email), and the third uses a non-standard value (phone-number instead of tel).

Correct: Valid autocomplete Values

<label for="name">Full Name</label>
<input type="text" id="name" name="name" autocomplete="name">

<label for="email">Email</label>
<input type="email" id="email" name="email" autocomplete="email">

<label for="phone">Phone</label>
<input type="tel" id="phone" name="phone" autocomplete="tel">

Correct: Using Multiple Tokens

When a form has separate shipping and billing sections, you can use additional tokens to distinguish them:

<fieldset>
  <legend>Shipping Address</legend>
  <label for="ship-street">Street Address</label>
  <input type="text" id="ship-street" name="ship-street"
    autocomplete="shipping street-address">

  <label for="ship-zip">Postal Code</label>
  <input type="text" id="ship-zip" name="ship-zip"
    autocomplete="shipping postal-code">
</fieldset>

<fieldset>
  <legend>Billing Address</legend>
  <label for="bill-street">Street Address</label>
  <input type="text" id="bill-street" name="bill-street"
    autocomplete="billing street-address">

  <label for="bill-zip">Postal Code</label>
  <input type="text" id="bill-zip" name="bill-zip"
    autocomplete="billing postal-code">
</fieldset>

Correct: Named Sections with section-*

You can use custom section names to group related fields when the same type of data appears multiple times:

<label for="home-tel">Home Phone</label>
<input type="tel" id="home-tel" name="home-tel"
  autocomplete="section-home tel">

<label for="work-tel">Work Phone</label>
<input type="tel" id="work-tel" name="work-tel"
  autocomplete="section-work tel">

By using valid, correctly applied autocomplete values, you ensure that assistive technologies can communicate the purpose of each field to users, browsers can offer reliable autofill, and your forms meet the requirements of WCAG 2.1 Success Criterion 1.3.5.

Some users need to adjust text spacing to make content readable. People with low vision may increase letter or word spacing to reduce visual crowding. People with cognitive disabilities, dyslexia, or attention deficit disorders often struggle to track lines of text that are tightly spaced — increasing line-height, letter-spacing, or word-spacing can make reading significantly easier.

When text-spacing properties are set inline with !important, they gain the highest specificity in the CSS cascade. This means user stylesheets, browser extensions, and assistive technology tools cannot override those values. The text becomes locked into a fixed spacing that may be difficult or impossible for some users to read.

This rule relates to WCAG 2.1 Success Criterion 1.4.12: Text Spacing (Level AA), which requires that no loss of content or functionality occurs when users adjust:

• Line height to at least 1.5 times the font size
• Spacing following paragraphs to at least 2 times the font size
• Letter spacing to at least 0.12 times the font size
• Word spacing to at least 0.16 times the font size

If inline !important declarations prevent these adjustments, the content fails this criterion.

How to Fix It

The fix is straightforward: do not use !important on inline style attributes for line-height, letter-spacing, or word-spacing. You have a few options:

1. Remove !important from the inline style declaration. Without !important, users can override the value with a custom stylesheet.
2. Move styles to an external or embedded stylesheet. This is generally the best approach because it separates content from presentation and gives users more control through the cascade.
3. If !important is truly necessary, apply it in a stylesheet rather than inline. Inline !important styles are virtually impossible for users to override, while stylesheet-level !important can still be overridden by user !important rules.

Note that other inline style properties like font-size are not flagged by this rule — only the three text-spacing properties (line-height, letter-spacing, word-spacing) are checked.

Examples

Incorrect: Inline styles with !important

These examples fail because !important on inline text-spacing properties prevents user overrides.

<!-- line-height with !important — cannot be overridden -->

<p style="line-height: 1.5 !important;">
  This text is locked to a specific line height.
</p>

<!-- letter-spacing with !important — cannot be overridden -->

<p style="letter-spacing: 2px !important;">
  This text has fixed letter spacing.
</p>

<!-- word-spacing with !important — cannot be overridden -->

<p style="word-spacing: 4px !important;">
  This text has fixed word spacing.
</p>

<!-- Mixed: word-spacing is fine, but letter-spacing has !important -->

<p style="word-spacing: 4px; letter-spacing: 2px !important; line-height: 1.8;">
  Even one !important on a spacing property causes a failure.
</p>

Correct: Inline styles without !important

These examples pass because users can override the inline values with a custom stylesheet.

<!-- line-height without !important — overridable -->

<p style="line-height: 1.5;">
  Users can adjust this line height with a custom stylesheet.
</p>

<!-- letter-spacing without !important — overridable -->

<p style="letter-spacing: 2px;">
  Users can adjust this letter spacing.
</p>

<!-- word-spacing without !important — overridable -->

<p style="word-spacing: 4px;">
  Users can adjust this word spacing.
</p>

<!-- Multiple spacing properties, all without !important -->

<p style="word-spacing: 4px; letter-spacing: 2px; line-height: 1.8;">
  All three spacing properties can be overridden by the user.
</p>

<!-- font-size with !important is fine — not a text-spacing property -->

<p style="font-size: 200%;">
  This does not trigger the rule.
</p>

Best practice: Use an external stylesheet instead

<!-- HTML -->

<p class="readable-text">
  Styles are defined in the stylesheet, giving users full control.
</p>

/* CSS */
.readable-text {
  line-height: 1.8;
  letter-spacing: 0.05em;
  word-spacing: 0.1em;
}

By keeping text-spacing styles in a stylesheet, you make it easy for users to apply their own overrides while maintaining your default design.

The <blink> element was once used to draw attention to content by making it flash repeatedly. While it may have seemed like an eye-catching effect, it creates serious accessibility barriers for multiple groups of users. The element has been deprecated from the HTML specification, and although most modern browsers no longer render the blinking effect, the element should still be removed from your markup to ensure compliance and avoid issues in any environment that might still support it.

Why this is an accessibility problem

Blinking content affects several groups of users:

• Users with cognitive disabilities may find blinking text distracting or incomprehensible. The constant flashing can make it very difficult to focus on and understand the content.
• Users with low vision struggle to read text that appears and disappears rapidly. The intermittent visibility makes the content effectively unreadable.
• Users with motor disabilities may have difficulty clicking on blinking links or buttons, since the target is not consistently visible and requires precise timing to activate.
• Users with photosensitive conditions can experience discomfort or, in extreme cases, seizures from flashing content, depending on the frequency.

This rule relates to WCAG 2.2 Success Criterion 2.2.2: Pause, Stop, Hide (Level A), which requires that for any moving, blinking, or scrolling content that starts automatically and lasts more than five seconds, users must be able to pause, stop, or hide it. Since the <blink> element provides no mechanism for users to control the flashing, it fails this criterion outright.

This rule also applies to Section 508 §1194.22(j), which states that pages must be designed to avoid causing the screen to flicker with a frequency greater than 2 Hz and lower than 55 Hz.

How to fix it

1. Remove all <blink> elements from your HTML. Replace them with standard elements like <span>, <strong>, or <em>.
2. Remove text-decoration: blink; from your CSS, as this is the CSS equivalent of the <blink> element.
3. Use alternative emphasis techniques to make content stand out — bold text, color, larger font size, borders, background highlights, or icons.

Important: Many modern browsers silently ignore the <blink> element, so the text won’t visually blink even though the element is present in the source code. Don’t rely on how the page looks in the browser to determine whether <blink> tags exist. Always check the actual HTML source.

Examples

Incorrect: using the <blink> element

<p><blink>Moving Sale Thursday!</blink></p>

This causes the text to flash on and off (in browsers that support it), making it inaccessible.

Incorrect: using text-decoration: blink in CSS

<style>
  .attention {
    text-decoration: blink;
  }
</style>
<h2 class="attention">Limited Time Offer!</h2>

The CSS text-decoration: blink value achieves the same inaccessible effect as the <blink> element.

Correct: using static visual emphasis

<p><strong>Moving Sale Thursday!</strong></p>

Using <strong> makes the text bold and conveys emphasis to screen readers without any flashing.

Correct: using CSS for visual emphasis without blinking

<style>
  .highlight {
    background-color: #fff3cd;
    border-left: 4px solid #ffc107;
    padding: 8px 12px;
    font-weight: bold;
  }
</style>
<p class="highlight">Limited Time Offer!</p>

This draws attention to the content using color, a border, and bold text — all without any flashing or blinking, keeping the content readable and accessible for everyone.

When a web page uses CSS media queries like @media (orientation: portrait) or @media (orientation: landscape) to force content into a single orientation, it prevents the page from responding to the user’s actual device position. This is checked by the axe rule css-orientation-lock.

Why this matters

Many users physically cannot rotate their devices. People with mobility impairments may have their phone or tablet mounted to a wheelchair, bed, or desk in a fixed orientation. Users with low vision may prefer landscape mode to enlarge text, while others may find portrait easier to read. Locking orientation removes their ability to choose what works best for them.

Beyond motor and vision disabilities, orientation locking also affects users with cognitive disabilities and dyslexia who may rely on a particular layout for readability. Sighted keyboard users who use external displays or stands may also be impacted.

This rule relates to WCAG 2.1 Success Criterion 1.3.4: Orientation (Level AA), which requires that content not restrict its view and operation to a single display orientation unless a specific orientation is essential. Essential use cases are rare — examples include a piano keyboard app, a bank check deposit interface, or a presentation slide display where the orientation is integral to the functionality.

How to fix it

1. Remove orientation-locking CSS. Look for @media queries that use the orientation feature combined with styles that effectively hide or completely rearrange content for only one orientation (e.g., setting display: none or width: 0 on the body or main content).
2. Use responsive design instead. Rather than checking orientation, use min-width or max-width media queries to adapt your layout to available space. This naturally accommodates both orientations.
3. Test in both orientations. Rotate your device or use browser developer tools to simulate both portrait and landscape modes. Verify that all content remains visible and functional.
4. Only lock orientation when essential. If your application genuinely requires a specific orientation for core functionality (not just aesthetic preference), document the rationale. This is the only valid exception.

Examples

Incorrect: Locking content to portrait only

This CSS hides the main content area when the device is in landscape orientation, effectively forcing users to use portrait mode:

<style>
  @media (orientation: landscape) {
    .content {
      display: none;
    }
    .rotate-message {
      display: block;
    }
  }
  @media (orientation: portrait) {
    .rotate-message {
      display: none;
    }
  }
</style>

<div class="content">
  <h1>Welcome to our site</h1>
  <p>This content is only visible in portrait mode.</p>
</div>
<div class="rotate-message">
  <p>Please rotate your device to portrait mode.</p>
</div>

Incorrect: Using transform to force portrait layout in landscape

<style>
  @media (orientation: landscape) {
    body {
      transform: rotate(-90deg);
      transform-origin: top left;
      width: 100vh;
      height: 100vw;
      overflow: hidden;
      position: absolute;
    }
  }
</style>

This forcibly rotates the entire page, fighting against the user’s chosen orientation and creating a confusing, inaccessible experience.

Correct: Responsive layout that works in both orientations

<style>
  .content {
    padding: 1rem;
  }
  .grid {
    display: grid;
    grid-template-columns: 1fr;
    gap: 1rem;
  }
  @media (min-width: 600px) {
    .grid {
      grid-template-columns: 1fr 1fr;
    }
  }
</style>

<div class="content">
  <h1>Welcome to our site</h1>
  <div class="grid">
    <div>
      <p>Column one content.</p>
    </div>
    <div>
      <p>Column two content.</p>
    </div>
  </div>
</div>

This approach uses min-width instead of orientation, adapting the layout based on available space. The content remains fully accessible and readable whether the device is held in portrait or landscape.

Correct: Using orientation queries for minor style adjustments (not locking)

<style>
  .hero-image {
    width: 100%;
    height: 200px;
    object-fit: cover;
  }
  @media (orientation: landscape) {
    .hero-image {
      height: 300px;
    }
  }
</style>

<img class="hero-image" src="hero.jpg" alt="A scenic mountain landscape">

Using orientation media queries is acceptable when you’re making minor visual adjustments without hiding or restricting access to content. The key is that all content and functionality remain available in both orientations.

Screen readers rely on distinct sound libraries for each language, with pronunciation rules, intonation patterns, and phonetics tailored to that specific language. When a user navigates to a page, the screen reader checks the lang attribute on the <html> element to determine which sound library to load. If no lang attribute is present, the screen reader falls back to whatever default language the user configured during setup. For someone who speaks multiple languages and browses websites in different languages, this creates a serious problem — the screen reader will attempt to read foreign-language content using the wrong pronunciation rules, producing garbled or incomprehensible speech.

This issue primarily affects blind and deafblind users who rely on screen readers, but it also impacts users with cognitive disabilities who may use text-to-speech tools. When text is read aloud with the wrong language rules, even simple words become unrecognizable, effectively making the content inaccessible.

Related WCAG Success Criteria

This rule maps to WCAG 2.0, 2.1, and 2.2 Success Criterion 3.1.1: Language of Page at Level A — the most fundamental level of conformance. This criterion requires that the default human language of each web page can be programmatically determined. It is also referenced by the Trusted Tester guidelines (11.A), EN 301 549, and RGAA.

How to Fix It

Add a lang attribute with a valid language code to the opening <html> element. The value should represent the primary language of the page content.

You can use a simple two-letter language code (like en for English, fr for French, or de for German), or you can be more specific with a regional dialect code like en-US for American English or fr-CA for Canadian French. A full list of valid language subtags is available in the IANA Language Subtag Registry.

If sections of your page contain content in a different language than the primary one, use the lang attribute on those specific elements so screen readers can switch sound libraries mid-page.

For languages written right to left (such as Arabic or Hebrew), also include the dir attribute with a value of rtl to indicate the text direction.

Examples

Incorrect: Missing lang attribute

This will trigger the rule because the <html> element has no lang attribute:

<html>
  <head>
    <title>My Website</title>
  </head>
  <body>
    <h1>Welcome</h1>
  </body>
</html>

Correct: lang attribute with a valid language code

<html lang="en">
  <head>
    <title>My Website</title>
  </head>
  <body>
    <h1>Welcome</h1>
  </body>
</html>

Correct: Using a regional dialect code

<html lang="en-US">
  <head>
    <title>My Website</title>
  </head>
  <body>
    <h1>Welcome</h1>
  </body>
</html>

Correct: Handling inline language changes

When a portion of the page is in a different language, use the lang attribute on the containing element:

<html lang="en">
  <head>
    <title>My Website</title>
  </head>
  <body>
    <p>The French word for hello is <span lang="fr">bonjour</span>.</p>
  </body>
</html>

Correct: Right-to-left language with dir attribute

<html lang="ar" dir="rtl">
  <head>
    <title>موقعي</title>
  </head>
  <body>
    <h1>مرحبا</h1>
  </body>
</html>

Screen readers rely on language-specific sound libraries to pronounce text accurately. Each language has its own pronunciation rules, intonation patterns, and phonetic characteristics, so screen readers load the appropriate library based on the declared language of the document. When the <html> element has no lang attribute or contains an invalid value — such as a misspelling or a fabricated code — the screen reader cannot determine which library to use. It defaults to whatever language the user configured during setup, which means content written in French might be read aloud using English pronunciation rules. The result is speech that sounds like a confusing, unintelligible accent.

This issue primarily affects blind users and deafblind users who rely on screen readers, but it also impacts users with cognitive disabilities who may use text-to-speech tools to aid comprehension. When pronunciation is wrong, understanding drops dramatically.

Related WCAG Success Criteria

This rule maps to WCAG Success Criterion 3.1.1: Language of Page (Level A), which requires that the default human language of each web page can be programmatically determined. This is a Level A requirement — the most fundamental level of accessibility — meaning it must be satisfied for basic compliance under WCAG 2.0, 2.1, and 2.2. It is also required by the Trusted Tester methodology, EN 301 549, and RGAA.

How to Fix It

1. Add a lang attribute to the opening <html> element.
2. Set its value to a valid BCP 47 language tag that represents the primary language of the page.
3. Double-check the spelling of the language code. Common valid codes include "en" (English), "fr" (French), "es" (Spanish), "de" (German), "ja" (Japanese), and "ar" (Arabic).
4. You can optionally include a regional subtag, such as "en-US" for American English or "fr-CA" for Canadian French.
5. For XHTML documents served as XML, use xml:lang instead of or in addition to lang.

If the language changes within the document for specific passages, use the lang attribute on the appropriate element to indicate the switch. For right-to-left languages, also include the dir="rtl" attribute.

Examples

Incorrect: Missing lang attribute

<html>
  <head>
    <title>My Page</title>
  </head>
  <body>
    <p>Welcome to my website.</p>
  </body>
</html>

Without a lang attribute, screen readers cannot determine the page language and will default to the user’s configured language, which may not match the content.

Incorrect: Invalid lang value

<html lang="english">
  <head>
    <title>My Page</title>
  </head>
  <body>
    <p>Welcome to my website.</p>
  </body>
</html>

The value "english" is not a valid BCP 47 language tag. The correct code for English is "en".

Correct: Valid lang attribute

<html lang="en">
  <head>
    <title>My Page</title>
  </head>
  <body>
    <p>Welcome to my website.</p>
  </body>
</html>

Correct: Regional subtag

<html lang="fr-CA">
  <head>
    <title>Ma page</title>
  </head>
  <body>
    <p>Bienvenue sur mon site web.</p>
  </body>
</html>

Correct: Language change within the page

<html lang="en">
  <head>
    <title>Multilingual Page</title>
  </head>
  <body>
    <p>This paragraph is in English.</p>
    <p lang="es">Este párrafo está en español.</p>
  </body>
</html>

Correct: Right-to-left language

<html lang="ar" dir="rtl">
  <head>
    <title>صفحتي</title>
  </head>
  <body>
    <p>مرحبا بكم في موقعي.</p>
  </body>
</html>

The dir="rtl" attribute ensures the text direction is correctly rendered for right-to-left languages like Arabic and Hebrew.

The lang attribute tells browsers and assistive technologies what language the content is written in. The xml:lang attribute serves the same purpose but comes from the XML/XHTML specification. When both attributes are present on the same element—most commonly the <html> element—they must agree on the base language. The “base language” is the primary language subtag (e.g., en in en-US or fr in fr-CA). If one attribute says en and the other says fr, assistive technologies receive conflicting information and cannot reliably determine how to process the content.

Who is affected

This issue primarily impacts screen reader users, including people who are blind, deafblind, or have cognitive disabilities. Screen readers maintain separate pronunciation libraries for each language. When they encounter a language declaration, they switch to the appropriate library so words are spoken with correct pronunciation and cadence. A mismatch between lang and xml:lang can cause the screen reader to select the wrong library or behave unpredictably, making the content difficult or impossible to understand.

Users who speak multiple languages and browse sites in different languages are especially vulnerable, as they rely on accurate language declarations to switch between language contexts.

Related WCAG success criteria

This rule relates to WCAG Success Criterion 3.1.1: Language of Page (Level A), which requires that the default human language of each web page can be programmatically determined. This criterion applies across WCAG 2.0, 2.1, and 2.2, as well as EN 301 549 and RGAA. When lang and xml:lang conflict, the programmatically determined language becomes ambiguous, violating this requirement.

How to fix it

1. Check the <html> element (and any other elements) for the presence of both lang and xml:lang attributes.
2. Ensure both attributes use the same base language. For example, if lang="en", then xml:lang must also start with en (e.g., en, en-US, or en-GB).
3. If you don’t need xml:lang, the simplest fix is to remove it entirely. The lang attribute alone is sufficient for HTML5 documents.
4. If you’re serving XHTML, both attributes may be required. In that case, keep them in sync.

You can find valid language codes on the ISO 639 language codes reference page. Common codes include en for English, fr for French, es for Spanish, de for German, and ar for Arabic.

Examples

Incorrect: mismatched base languages

The lang attribute specifies English, but xml:lang specifies French. This creates a conflict that confuses assistive technologies.

<html lang="en" xml:lang="fr">
  <head>
    <title>My Page</title>
  </head>
  <body>
    <p>Hello, world!</p>
  </body>
</html>

Correct: matching base languages

Both attributes specify English. The dialect subtag may differ, but the base language (en) is the same.

<html lang="en-US" xml:lang="en-GB">
  <head>
    <title>My Page</title>
  </head>
  <body>
    <p>Hello, world!</p>
  </body>
</html>

Correct: identical values

The simplest and most reliable approach—use the exact same value for both attributes.

<html lang="en" xml:lang="en">
  <head>
    <title>My Page</title>
  </head>
  <body>
    <p>Hello, world!</p>
  </body>
</html>

Correct: only lang attribute (HTML5)

In HTML5 documents, the xml:lang attribute is not required. Using lang alone avoids any possibility of a mismatch.

<html lang="en">
  <head>
    <title>My Page</title>
  </head>
  <body>
    <p>Hello, world!</p>
  </body>
</html>

Correct: specifying language on inline elements

When content in a different language appears within the page, use the lang attribute on the appropriate element. If you also use xml:lang, make sure they match.

<p>Welcome to our site. <span lang="es" xml:lang="es">Bienvenidos a nuestro sitio.</span></p>

For right-to-left languages, also include the dir attribute:

<p lang="ar" xml:lang="ar" dir="rtl">مرحبا بكم في موقعنا</p>

The <marquee> element was never part of any official HTML standard and has been deprecated by all major browsers. It produces text that continuously scrolls across the screen, making it extremely difficult to read, interact with, or comprehend. Even though browsers may still render it, the element should never appear in modern web content.

Why This Is an Accessibility Problem

Scrolling marquee text creates barriers for several groups of users:

• Users with low vision may not be able to read text that is constantly in motion. The movement makes it nearly impossible to track and process the words.
• Users with cognitive disabilities or attention deficits can be distracted or overwhelmed by content that moves without their control. Automatic motion competes for attention and can make it difficult to focus on other parts of the page.
• Users with limited motor skills may be unable to accurately click on links or interactive elements embedded within scrolling content, since the targets are constantly shifting position.
• Screen reader users may encounter inconsistent or confusing output, since the <marquee> element is non-standard and assistive technologies are not required to support it.

This rule relates to WCAG 2.2 Success Criterion 2.2.2: Pause, Stop, Hide (Level A), which requires that for any moving, blinking, or scrolling content that starts automatically and lasts more than five seconds, there must be a mechanism for users to pause, stop, or hide it. The <marquee> element provides no such mechanism by default, making it a failure of this criterion. This is also documented as a known failure technique: F16: Failure of Success Criterion 2.2.2 due to including scrolling content where movement is not essential to the activity without also including a mechanism to pause and restart the content.

How to Fix It

The fix is straightforward: remove all <marquee> elements from your HTML, including empty ones. Then decide how to handle the content:

1. Display the content as static text. In most cases, this is the best approach. Simply place the text in a standard element like a <p> or <span>.
2. If motion is truly needed, use CSS animations instead, and provide a visible control (such as a pause button) that allows users to stop the animation. Ensure the animation also respects the prefers-reduced-motion media query.

Examples

Incorrect: Using the <marquee> Element

This code uses the deprecated <marquee> element to create scrolling text with links. Users cannot pause or stop the movement.

<marquee behavior="scroll" direction="left">
  Frisbeetarianism is the
  <a href="https://en.wikipedia.org/wiki/Belief">belief</a> that when you
  <a href="https://en.wikipedia.org/wiki/Death">die</a>, your
  <a href="https://en.wikipedia.org/wiki/Soul">soul</a> goes up on the
  <a href="https://en.wikipedia.org/wiki/Roof">roof</a> and gets stuck.
</marquee>

Correct: Static Text

The simplest and most accessible fix is to display the content as regular, non-moving text.

<p>
  Frisbeetarianism is the
  <a href="https://en.wikipedia.org/wiki/Belief">belief</a> that when you
  <a href="https://en.wikipedia.org/wiki/Death">die</a>, your
  <a href="https://en.wikipedia.org/wiki/Soul">soul</a> goes up on the
  <a href="https://en.wikipedia.org/wiki/Roof">roof</a> and gets stuck.
</p>

Correct: CSS Animation with Pause Control and Reduced Motion Support

If scrolling text is a design requirement, use CSS with a pause button and respect the user’s motion preferences.

<div class="scrolling-container">
  <p class="scrolling-text" id="ticker">
    Breaking news: Accessibility makes the web better for everyone.
  </p>
  <button type="button" onclick="document.getElementById('ticker').classList.toggle('paused')">
    Pause / Resume
  </button>
</div>

<style>
  .scrolling-text {
    animation: scroll-left 10s linear infinite;
  }
  .scrolling-text.paused {
    animation-play-state: paused;
  }
  @keyframes scroll-left {
    from { transform: translateX(100%); }
    to { transform: translateX(-100%); }
  }
  @media (prefers-reduced-motion: reduce) {
    .scrolling-text {
      animation: none;
    }
  }
</style>

This approach gives users control over the motion and automatically disables the animation for users who have indicated they prefer reduced motion in their operating system settings.

When a <video> or <audio> element plays sound automatically, it competes with assistive technology output. Screen reader users rely on hearing their screen reader’s spoken output to navigate and interact with web content. If background audio starts playing as soon as they land on a page, it can drown out the screen reader, making it difficult or impossible to find and operate the very control needed to stop the unwanted sound. This creates a frustrating catch-22: the user needs to hear their screen reader to find the stop button, but the auto-playing audio prevents them from hearing the screen reader.

People with cognitive disabilities can also be significantly affected, as unexpected audio can be disorienting, distracting, and make it harder to process page content.

Related WCAG Success Criteria

This rule maps to WCAG Success Criterion 1.4.2: Audio Control (Level A), which requires that if any audio on a web page plays automatically for more than three seconds, either a mechanism is available to pause or stop the audio, or a mechanism is available to control audio volume independently from the overall system volume level. This is a Level A requirement, meaning it is considered a minimum baseline for accessibility across WCAG 2.0, 2.1, and 2.2.

How to Fix the Problem

Use one of the following approaches:

1. Don’t autoplay audio (strongly preferred). Let the user initiate playback themselves. This is the best approach because it gives users full control and avoids any interference with assistive technology.

2. Keep auto-playing audio under three seconds. If the audio stops within three seconds and does not loop, it is unlikely to significantly disrupt screen reader usage.

3. Provide an accessible control mechanism. If audio must autoplay for more than three seconds, include a clearly visible, keyboard-accessible control near the top of the page that allows users to pause, stop, or mute the audio. The control must be reachable before the user needs to navigate through a lot of content.

Important Considerations

• The controls attribute on <audio> and <video> elements satisfies the requirement for a control mechanism, as it provides built-in browser controls for play, pause, and volume.
• A short audio clip that uses the loop attribute will effectively play indefinitely, so it fails this rule even if the source file is under three seconds.
• Custom controls must be keyboard accessible and properly labeled for screen readers.

Examples

Failing: Autoplay with no controls

This <audio> element autoplays and provides no way for the user to stop or mute it:

<audio autoplay src="background-music.mp3">
</audio>

Failing: Short audio that loops indefinitely

Even though the audio file is under three seconds, the loop attribute causes it to repeat forever:

<audio autoplay loop src="chime.mp3">
</audio>

Failing: Video with autoplay and no controls

<video autoplay src="promo.mp4">
</video>

Passing: Autoplay with built-in controls

Adding the controls attribute gives users the ability to pause, stop, and adjust volume:

<audio autoplay controls src="background-music.mp3">
</audio>

<video autoplay controls src="promo.mp4">
</video>

Passing: No autoplay — user initiates playback

The best approach is to let the user decide when to start playback:

<audio controls src="background-music.mp3">
</audio>

Passing: Autoplay with short duration and no loop

If the audio is under three seconds and does not loop, it is acceptable:

<video autoplay src="short-intro.mp4">
</video>

Passing: Autoplay with a custom accessible mute button

If you cannot use the native controls attribute, provide a custom control that is keyboard accessible and labeled:

<audio id="bg-audio" autoplay src="background-music.mp3">
</audio>
<button type="button" onclick="document.getElementById('bg-audio').pause()">
  Pause background audio
</button>

How the Rule Works

The axe-core rule no-autoplay-audio evaluates <audio> and <video> elements and checks whether they autoplay audio for more than three seconds without a control mechanism. Specifically:

• If the element has no source, the result is incomplete (duration cannot be determined).
• If the element can autoplay and has no controls mechanism, it fails.
• If the element plays under three seconds but loops, it fails (because the effective duration is infinite).
• If the element can autoplay but has a controls mechanism, it passes.
• If the element can autoplay and the duration is under three seconds (without looping), it passes.

Screen readers rely on language information to select the correct pronunciation engine for content. Each language has its own sound library with unique pronunciation rules, intonation, and phonetic patterns. When a screen reader encounters a lang attribute with a valid value, it seamlessly switches to the appropriate library. But when the value is invalid — for example, lang="egnlish" instead of lang="en" — the screen reader cannot identify the language and falls back to its default, reading the foreign-language text with completely wrong pronunciation.

This primarily affects blind users and deafblind users who depend on screen readers, as well as users with cognitive disabilities who may rely on text-to-speech tools. Imagine hearing Spanish text pronounced with English phonetic rules — it would be nearly incomprehensible.

Note that this rule specifically checks lang attributes on elements within the page (not the <html> element itself, which is covered by a separate rule). It applies whenever you use the lang attribute to indicate that a section of content is in a different language than the rest of the page.

Related WCAG Success Criteria

This rule maps to WCAG 2.0 / 2.1 / 2.2 Success Criterion 3.1.2: Language of Parts (Level AA). This criterion requires that the human language of each passage or phrase in the content can be programmatically determined, except for proper names, technical terms, and words of indeterminate language. Using a valid language code is essential to meeting this requirement — an invalid code fails to programmatically convey the language.

This rule is also referenced by the Trusted Tester methodology, EN 301 549, and RGAA.

How to Fix It

1. Use valid language codes. Language values must conform to the BCP 47 standard. In practice, this means using two- or three-letter codes from the IANA Language Subtag Registry. Common examples include en (English), fr (French), es (Spanish), de (German), zh (Chinese), ar (Arabic), and ja (Japanese).

2. Check for typos. Invalid values are often caused by misspellings (e.g., lang="enlish") or using full language names instead of codes (e.g., lang="French" instead of lang="fr").

3. Use dialect subtags when appropriate. You can specify regional variants such as en-US (American English), en-GB (British English), or fr-CA (Canadian French). The primary subtag alone is also valid.

4. Set the dir attribute for RTL languages. If you’re marking content in a right-to-left language like Arabic or Hebrew, pair the lang attribute with dir="rtl" to ensure correct text rendering.

Examples

Incorrect: Invalid language code

<p>Welcome to our site. <span lang="spn">Bienvenidos a nuestro sitio.</span></p>

The value spn is not a valid language subtag. Screen readers cannot identify this as Spanish.

Incorrect: Full language name instead of code

<p>Here is a quote: <q lang="Japanese">素晴らしい</q></p>

The value Japanese is not a valid BCP 47 language code.

Correct: Valid two-letter language code

<p>Welcome to our site. <span lang="es">Bienvenidos a nuestro sitio.</span></p>

The value es is the valid language subtag for Spanish.

Correct: Valid language code with regional subtag

<p>The Canadian term is <span lang="fr-CA">dépanneur</span>.</p>

The value fr-CA correctly identifies Canadian French.

Correct: RTL language with direction attribute

<p>The Arabic word for peace is <span lang="ar" dir="rtl">سلام</span>.</p>

The value ar is the valid subtag for Arabic, and dir="rtl" ensures proper text directionality.

Correct: Multiple language switches on one page

<p>
  In English we say "goodbye," in German it's
  <span lang="de">Auf Wiedersehen</span>, and in Japanese it's
  <span lang="ja">さようなら</span>.
</p>

Each inline element uses a valid language code, allowing the screen reader to switch pronunciation engines as needed.