aria-labelledby

Cuándo usarlo

Cuando una parte del texto visible en la página ya describe el elemento — un encabezado sobre un diálogo, una cabecera de columna sobre una celda, un párrafo que introduce una región. aria-labelledby apunta a ese texto para que el lector de pantalla lo anuncie como el nombre accesible del elemento. El usuario escucha exactamente lo que lee un usuario vidente.

El equivalente HTML nativo es <label for="…"> en los campos de formulario. aria-labelledby extiende la misma idea a cualquier rol que admita nombre.

Cómo funciona

El valor es una lista de IDs de elementos separados por espacios. La tecnología de apoyo recoge el contenido textual de cada elemento referenciado, en orden, los une con espacios y usa el resultado como nombre accesible. Las referencias a elementos ocultos (display: none, hidden) siguen contribuyendo con su texto — el elemento solo necesita estar en el DOM.

aria-labelledby tiene precedencia sobre aria-label, que a su vez tiene precedencia sobre el texto interno visible. Por tanto, si se apunta al encabezado visible, no hace falta también un aria-label.

Para mantener válida la relación: los IDs referenciados deben existir en la página, deben ser únicos, y el texto que contienen debe mantenerse significativo. Si se vuelve a renderizar un panel de pestañas reutilizando IDs, se debe verificar que el nuevo contenido siga describiendo el elemento etiquetado.

Fallos habituales

• Apuntar a un ID que no existe (error tipográfico, elemento eliminado, componente desmontado). La relación falla silenciosamente y el elemento queda sin nombre.
• Reutilizar el mismo ID dos veces en la página — solo cuenta la primera coincidencia.
• Referenciar un elemento cuyo texto está vacío o contiene solo espacios en blanco.
• Concatenación en orden incorrecto: aria-labelledby="apellido nombre" produce «García Juan» cuando se quería «Juan García».
• Apuntar a un <div> genérico que contiene un párrafo largo — todo el párrafo se convierte en el nombre. Los nombres deben ser breves; el contexto extenso pertenece a aria-describedby.
• Olvidar actualizar el texto referenciado al localizar — los nombres quedan desincronizados con la interfaz visible.

Ejemplo

<h2 id="billing-heading">Dirección de facturación</h2>
<div role="group" aria-labelledby="billing-heading">
  <label>
    Calle
    <input type="text" autocomplete="street-address">
  </label>
  <!-- … -->
</div>

<!-- Dos IDs concatenados para el patrón «nombre + apellido» -->
<span id="first">Nombre</span>
<span id="last">(obligatorio)</span>
<input type="text" aria-labelledby="first last">