Helpful error suggestions and the ADA

From "what" to "how": giving people a way out

Telling someone a field is wrong is only half the job. WCAG 2.1 success criterion 3.3.3 (Level AA) says that if an input error is automatically detected and suggestions for correction are known, the suggestions are provided to the user, unless that would jeopardize the security or purpose of the content.

The key words are "are known". If the site knows the field needs five digits, or that the only valid options are three time slots, it should say so. Suggestions can come from the author or from the user agent. They help people with cognitive disabilities, low vision and motor impairments to fix the error with fewer attempts, and they reduce abandoned forms.

When you may hold back

• The suggestion would weaken security, for example telling someone which of username or password was wrong at sign-in.
• The suggestion would defeat the purpose of the content, for example a quiz that tests whether people know a spelling.
• No suggestion is actually known. The criterion does not ask you to invent one.

The ADA angle: errors on forms people have to complete

Residents use public forms to book, pay, apply and report. "Invalid entry" on a park reservation or a license renewal sends them back to guess. DOJ's guidance lists unclear instructions and missing error alerts among the barriers on forms; a message that says how to fix a problem is one way to give clear instructions. See also mobile apps, where small keyboards make retyping costly.

Web code: ZIP codes, date ranges, full slots, parcel numbers

ZIP code

<p class="error" id="zip-err">Invalid ZIP.</p>

<p class="error" id="zip-err">
  ZIP code: enter 5 digits, for example 94103. You entered 4.
</p>

Reservation dates in the wrong order

<p class="error">Date error.</p>

<p class="error">
  Check-out must be after check-in (June 14).
  <button type="button" data-set="checkout" data-value="2026-06-15">Use June 15</button>
</p>

Appointment slot already taken

<p class="error">That time is not available.</p>

<p class="error">9:00 AM is full. Available times on this day:</p>
<ul>
  <li><button type="button" data-time="09:30">9:30 AM</button></li>
  <li><button type="button" data-time="10:15">10:15 AM</button></li>
</ul>

Mobile code: SwiftUI and Jetpack Compose

// SwiftUI
if zip.count != 5 { Text("Invalid ZIP").foregroundColor(.red) }

// SwiftUI
if zip.count != 5 {
  Text("ZIP code: enter 5 digits. You entered \(zip.count).")
    .foregroundColor(.red)
}

// Jetpack Compose
OutlinedTextField(
  value = zip, onValueChange = { zip = it },
  isError = zip.length != 5,
  supportingText = { if (zip.length != 5) Text("Invalid ZIP") }
)

// Jetpack Compose
OutlinedTextField(
  value = zip, onValueChange = { zip = it },
  isError = zip.length != 5,
  supportingText = {
    if (zip.length != 5) Text("ZIP code: enter 5 digits. You entered ${zip.length}.")
  }
)

Test pass for error wording

1. Enter a wrong value in each field and read the message. Does it explain what a valid value looks like?
2. Where only a short list of values is valid, check that the list is offered or named.
3. Look for messages like "Invalid", "Error" and "Not allowed" on their own.
4. Confirm that the suggestion is repeated in text, not shown only in a placeholder that disappears.
5. Tools do not judge usefulness. A checker can flag an empty or very short message string; reading each message is the real test.

Weak messages to retire

• "Invalid", "Error", "Incorrect value" with nothing else.
• Format examples that only appear before the error and vanish afterwards.
• Suggesting the same wrong value again ("Did you mean 94103?" when they typed 94103).
• Telling the user what is wrong but not how to fix it when the fix is obvious to the developer.

Ship it when

• Errors with a known fix state the fix in text.
• Offered suggestions are real, valid values.
• Where a suggestion would expose security details, the message stays general on purpose.

Sources

• Understanding SC 3.3.3: Error Suggestion (W3C), opens in a new tab
• 28 CFR Part 35, Subpart H: Accessibility of Web Information and Services (eCFR), opens in a new tab

Standard version: WCAG 2.1 (W3C Recommendation, 5 June 2018), as named in the Title II web rule. This page is for informational purposes only and is not legal advice. For binding requirements, refer to the official ADA statute and regulations, and ask a lawyer how they apply to you.