Cuándo usar aria-label, aria-labelledby, aria-describedby o simplemente texto visible, con 20 fragmentos antes y después, errores comunes y un comprobador de nombres accesibles.
Usa aria-label solo cuando un elemento no tenga texto visible que lo nombre, como un botón que solo muestra un icono: <button aria-label="Close dialog">. Si ya hay texto visible que lo nombra, apóyate en él o apunta aria-labelledby hacia ese texto. aria-describedby añade ayuda adicional que se lee después del nombre. Las etiquetas nativas de HTML siempre van primero.
Qué herramienta usar para dar nombre
Cada botón, enlace, campo y punto de referencia necesita un nombre accesible, la frase corta que la tecnología de asistencia pronuncia cuando el foco llega ahí. Esta página muestra cómo se calcula ese nombre, veinte patrones defectuosos junto a sus versiones corregidas y un comprobador que lee un fragmento pegado e indica el nombre que recibiría.
aria-label guarda el nombre como una cadena dentro del atributo. aria-labelledby apunta a uno o más ids de elementos y construye el nombre a partir de su texto, así que el nombre siempre coincide con lo que ven los usuarios videntes. Cuando están los dos, gana aria-labelledby.
Sí. En la mayoría de los controles el valor de aria-label reemplaza al contenido de texto, así que un botón que muestra Comprar y lleva aria-label="Add to basket" se anuncia como Añadir a la cesta. Esa discrepancia confunde a quienes usan control por voz e incumple el criterio WCAG 2.5.3 Etiqueta en el nombre.
Úsalo para información de apoyo que no es el nombre: una regla de contraseña, una pista de formato o un mensaje de error. Los lectores de pantalla suelen leer la descripción después del nombre y el rol, a menudo tras una breve pausa, y algunos usuarios desactivan las descripciones.
Solo si el div tiene un rol que permita nombrarlo, como role="region" o role="dialog". En un div o span genérico, ARIA prohíbe darle nombre y la mayoría de los lectores de pantalla ignoran el atributo.
No. Las imágenes toman su nombre del atributo alt. Usa alt="" para las decorativas y así se omiten. aria-label en un img funciona, pero no aporta nada que alt no pueda hacer.
Recorre esta lista de arriba abajo y quédate con la primera opción que encaje. El texto visible va primero porque sirve con una sola cadena a usuarios videntes, de lector de pantalla y de control por voz.
Las cuatro formas de dar a un elemento su nombre o descripción
Cada fragmento muestra el patrón defectuoso, la corrección y, aproximadamente, lo que dice un lector de pantalla tras la corrección. Los anuncios varían según el producto y la configuración.
Sin nombre, el botón suele anunciarse solo como botón. Oculta el dibujo para que no se lea como una imagen sin etiqueta. Tras la corrección suele anunciarse así: Cerrar, botón.
Un enlace vacío suele leerse como su URL, letra por letra en algunas configuraciones. Tras la corrección suele anunciarse así: Nuestra tienda en Instagram, enlace.
El texto real dentro de un span oculto visualmente resiste las herramientas de traducción, que tienden a saltarse los valores de los atributos. Tras la corrección suele anunciarse así: Carrito, 3 artículos, enlace.
Con dos elementos nav sin nombre, la lista de puntos de referencia muestra navegación dos veces y nadie puede distinguirlos. Tras la corrección suele anunciarse así: Principal, navegación.
El texto del placeholder es un nombre de reserva débil y desaparece en cuanto alguien escribe. Tras la corrección suele anunciarse así: Buscar productos, campo de búsqueda.
Un elemento label real también hace clicable el rótulo, lo que amplía el área de pulsación. Tras la corrección suele anunciarse así: Email, campo de texto.
Las descripciones se unen en el orden en que se listan los ids. Tras la corrección suele anunciarse así: Contraseña, campo de texto seguro, entrada no válida, Al menos 12 caracteres, Demasiado corta....
La leyenda nombra el grupo, así que cada opción se entiende por sí sola. Tras la corrección suele anunciarse así: Velocidad de entrega, grupo, Estándar, botón de opción, 1 de 2.
Apuntar al encabezado visible mantiene idénticos el título hablado y el mostrado. Ábrelo con showModal() para un modal de verdad. Tras la corrección suele anunciarse así: ¿Eliminar proyecto?, diálogo, Esto elimina las 14 páginas..
Mantén el nombre fijo y deja que cambie el estado. No cambies además la etiqueta a Quitar negrita. Tras la corrección suele anunciarse así: Negrita, botón de alternancia, presionado.
Cambiar a la vez la etiqueta y un estado presionado se lee como una doble negación. Tras la corrección suele anunciarse así: Silenciar, botón de alternancia, no presionado.
El script debe cambiar aria-expanded y el atributo hidden a la vez. Tras la corrección suele anunciarse así: Productos, botón, contraído.
Un div clicable no recibe el foco ni se anuncia como control. Tras la corrección suele anunciarse así: Menú, botón, contraído.
Escribe lo que la imagen le cuenta al lector. Un alt vacío marca la decoración para que se omita. Tras la corrección suele anunciarse así: Las ventas subieron de 40 a 65 pedidos por semana en mayo, imagen.
role=img convierte el SVG en un único objeto en lugar de un árbol de formas. Tras la corrección suele anunciarse así: Northgate Bakery, imagen.
Un caption visible nombra la tabla para todos. Usa aria-labelledby solo cuando el título está fuera de ella. Tras la corrección suele anunciarse así: Horario de apertura, tabla, 2 columnas, 8 filas.
La región debe existir antes de que cambie su texto, o muchos lectores no captan la actualización. Tras la corrección suele anunciarse así: Guardado (se pronuncia sin mover el foco).
aria-roledescription cambia el rol pronunciado. Úsalo con moderación y nunca en elementos genéricos. Tras la corrección suele anunciarse así: Fotos de clientes, carrusel.
Un texto de enlace único ayuda a cualquiera que recorra una lista de enlaces. Empezar con las palabras visibles mantiene intacto Etiqueta en el nombre. Tras la corrección suele anunciarse así: Leer más sobre el horario de invierno, enlace.
Quien diga pulsa Enviar al control por voz debe activar este botón, así que la palabra visible tiene que estar en el nombre. Tras la corrección suele anunciarse así: Enviar, botón.
Errores vistos en auditorías y sus correcciones
Revisa los nombres antes de publicar
Pega un fragmento. El comprobador lo analiza en tu navegador sin ejecutar ningún script, encuentra el primer elemento interactivo o con nombre y calcula un nombre con una versión reducida del orden oficial. Se salta varios pasos de la especificación, así que tómalo como una pista rápida y confírmalo en las herramientas de desarrollo o con un lector de pantalla.
Botón de icono
Botón de icono corregido
Campo con etiqueta
Etiqueta que no coincide
Diálogo con labelledby
Fragmento HTML
No se encontró ningún botón, enlace, campo, punto de referencia, imagen ni tabla en el fragmento.
Elemento
Nombre calculado
(vacío)
Origen del nombre
Avisos
Esta comprobación simplificada no encontró ninguno.
elemento label
contenido de texto
title del svg
title (reserva débil)
placeholder (reserva débil)
aria-labelledby apunta al id inexistente "{id}".
La mayoría de los lectores de pantalla ignoran aria-label en un div o span sin rol.
La imagen no tiene atributo alt.
El placeholder es el único nombre. Añade una etiqueta.
No se encontró ningún nombre accesible.
El texto visible "{visible}" no está al principio del nombre (WCAG 2.5.3 Etiqueta en el nombre).
El nombre termina con una palabra de rol, así que el rol se pronunciará dos veces.
El propio elemento tiene aria-hidden.
Empieza gratis · Sin tarjeta de crédito