aria-describedby

Cuándo utilizarlo

Para información complementaria que aparece junto a un control: una indicación de formato bajo un campo de fecha («MM/DD/AAAA»), una lista de reglas de seguridad de contraseña, un mensaje de error en línea, las instrucciones que aparecen encima de un widget complejo. La etiqueta responde a ¿qué es esto?; la descripción responde a ¿hay algo más que deba saber?.

Debe usarse en campos de formulario, botones, diálogos y cualquier widget personalizado donde el contexto adicional pertenezca tras el nombre.

Cómo funciona

El valor es una lista de IDs de elementos separados por espacios, con la misma forma que aria-labelledby. Los lectores de pantalla anuncian la descripción tras el nombre accesible y el rol, normalmente después de una breve pausa — «Correo electrónico, campo de edición, Solo nos pondremos en contacto con usted en relación con este pedido.» Varios IDs se concatenan en el orden en que aparecen en la lista.

La descripción no es el nombre. No aparece en el campo de nombre del árbol de accesibilidad, por lo que axe-core no la contabilizará como etiqueta del control. Si el control no tiene nombre, aria-describedby no puede subsanarlo.

Si la descripción cambia (por ejemplo, aparece un error), conviene actualizar el contenido de texto del elemento referenciado en lugar de cambiar el valor de aria-describedby — muchas tecnologías de apoyo no reanuncian cuando el propio atributo cambia, pero sí cuando el texto referenciado forma parte de una región dinámica o cuando el foco vuelve a entrar en el campo.

Errores frecuentes

• Usar aria-describedby para lo que debería ser el nombre. El control sigue sin tener etiqueta; el usuario escucha la descripción pero nunca el nombre.
• Apuntar a un ID que no existe o que ha sido eliminado del DOM por un renderizado.
• Añadir aria-describedby a un elemento no enfocable. La mayoría de los navegadores exponen la descripción solo cuando el elemento recibe el foco o se consulta directamente.
• Incluir texto de marketing extenso como descripción — los anuncios verbosos llevan a los usuarios a desactivar las descripciones de forma global.
• Olvidar asociar los errores de formulario en línea. aria-describedby="email-error" junto con aria-invalid="true" es el patrón canónico; sin la referencia, el error es visible pero silencioso.
• Reutilizar el mismo ID de descripción para muchos campos con aria-describedby="hint" — funciona, pero conviene comprobar que el mismo texto se aplica realmente a todos los campos.

Ejemplo

<label for="password">Password</label>
<input
  id="password"
  type="password"
  aria-describedby="pw-rules pw-error"
  aria-invalid="true"
>
<p id="pw-rules">At least 12 characters, including a number.</p>
<p id="pw-error">Password is too short.</p>