From 49f8f76691ded939ac13a2327a7bbdfa1ea7db86 Mon Sep 17 00:00:00 2001 From: Joy Serquina Date: Thu, 13 Aug 2026 14:57:05 -0700 Subject: [PATCH] docs(material/form-field): update form-field prefix suffix a11y docs Updates Form Field components' documentation on accessibility when using matTextPrefix and matTextSuffix by recommending usage of aria-label or aria-describedby to ensure full context is provided for screen readers. Fixes b/517657863 --- src/material/form-field/form-field.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/material/form-field/form-field.md b/src/material/form-field/form-field.md index bdcf41bcd117..b89d1dbac824 100644 --- a/src/material/form-field/form-field.md +++ b/src/material/form-field/form-field.md @@ -144,6 +144,18 @@ adds these elements' IDs to the control's `aria-describedby` attribute. Addition applies `aria-live="polite"` by default such that assistive technology will announce errors when they appear. +When using static text prefixes or suffixes (such as currency symbols like `$` or unit suffixes like +`.00` or `kg`), screen readers may not announce them as part of the input value, and some mobile screen +readers, especially on Android/TalkBack, may expose them as separate focus stops. This can lead to +redundant announcements or unexpected focus behavior when navigating the field. + +If the prefix or suffix provides important context, add an `aria-label` to the input or include the full +meaning in `aria-describedby` so the accessible name/description matches the visible content. For example, +if the prefix is `$` and the suffix is `.00` to indicate dollars with no cents, an appropriate `aria-label` +could be `aria-label="Amount in dollars with 0 cents"`. When the static text is purely decorative and the +input already conveys the full context, add `aria-hidden="true"` to the static `matTextPrefix` or +`matTextSuffix` elements so they are skipped during swipe navigation and do not create redundant focus stops. + ### Troubleshooting #### Error: A hint was already declared for align="..."