El atributo “aria-controls” debe apuntar a un elemento en el mismo documento.

El atributo aria-controls establece una relación programática entre un elemento controlador (como un botón, pestaña o barra de desplazamiento) y el elemento que controla (como un panel, región o área de contenido). Las tecnologías de apoyo como los lectores de pantalla usan esta relación para ayudar a los usuarios a navegar entre elementos relacionados — por ejemplo, anunciando que un botón controla un panel específico y permitiendo al usuario saltar a él.

Cuando el id referenciado en aria-controls no existe en el documento, la relación se rompe. Los lectores de pantalla pueden intentar localizar el elemento objetivo y fallar silenciosamente, o pueden anunciar una relación de control que no lleva a ninguna parte. Esto degrada la experiencia para usuarios que dependen de tecnología de apoyo y viola la especificación WAI-ARIA, que requiere que el valor de aria-controls sea una lista de referencia ID válida que apunte a elementos en el mismo documento.

Las causas comunes de este error incluyen:

• Errores tipográficos en el id o el valor de aria-controls.
• Contenido generado dinámicamente donde el elemento controlado aún no se ha renderizado o ha sido eliminado del DOM.
• Errores de copiar-pegar donde aria-controls fue copiado de otro componente pero el id correspondiente no fue actualizado.
• Referenciar elementos en iframes o shadow DOM, que se consideran contextos de documento separados.

El atributo aria-controls acepta una o más referencias ID separadas por espacios. Cada ID listado debe coincidir con un elemento en el mismo documento.

Cómo solucionarlo

1. Verifica que el elemento objetivo existe en el documento y tiene exactamente el id que aria-controls referencia.
2. Comprueba errores tipográficos — la coincidencia de ID es sensible a mayúsculas, así que mainPanel y mainpanel no son lo mismo.
3. Si el elemento controlado se añade dinámicamente, asegúrate de que esté presente en el DOM antes o al mismo tiempo que el elemento controlador, o actualiza aria-controls programáticamente cuando el objetivo esté disponible.
4. Si el elemento controlado genuinamente está ausente (ej., renderizado condicionalmente), elimina el atributo aria-controls hasta que el elemento objetivo exista.

Ejemplos

Incorrecto: aria-controls referencia un ID no existente

<button aria-controls="info-panel" aria-expanded="false">
  Toggle Info
</button>

<div id="infopanel">
  <p>Here is some additional information.</p>
</div>

Esto desencadena el error porque aria-controls="info-panel" no coincide con el id real de "infopanel" (nota el guión faltante).

Correcto: aria-controls coincide con el ID de un elemento existente

<button aria-controls="info-panel" aria-expanded="false">
  Toggle Info
</button>

<div id="info-panel">
  <p>Here is some additional information.</p>
</div>

Correcto: relación entre pestaña y panel de pestaña

<div role="tablist">
  <button role="tab" aria-controls="tab1-panel" aria-selected="true">
    Overview
  </button>
  <button role="tab" aria-controls="tab2-panel" aria-selected="false">
    Details
  </button>
</div>

<div id="tab1-panel" role="tabpanel">
  <p>Overview content goes here.</p>
</div>

<div id="tab2-panel" role="tabpanel" hidden>
  <p>Details content goes here.</p>
</div>

Ambos valores de aria-controls — tab1-panel y tab2-panel — corresponden correctamente a elementos presentes en el documento.

Correcto: barra de desplazamiento personalizada controlando una región

<div role="scrollbar" aria-controls="main-content" aria-valuenow="0" aria-valuemin="0" aria-valuemax="100" aria-orientation="vertical"></div>

<div id="main-content" role="region" aria-label="Main content">
  <p>Scrollable content goes here.</p>
</div>

Correcto: controlar múltiples elementos

El atributo aria-controls puede referenciar múltiples IDs separados por espacios. Cada ID debe existir en el documento.

<button aria-controls="section-a section-b">
  Expand All Sections
</button>

<div id="section-a">
  <p>Section A content.</p>
</div>

<div id="section-b">
  <p>Section B content.</p>
</div>

Más información:

W3C Reference

W3C WAI ARIA 1.2 aria-controls

→