O atributo “aria-controls” deve apontar para um elemento no mesmo documento.

O atributo aria-controls estabelece uma relação programática entre um elemento de controlo (como um botão, separador ou barra de deslocamento) e o elemento que controla (como um painel, região ou área de conteúdo). Tecnologias assistivas, como leitores de ecrã, usam esta relação para ajudar os utilizadores a navegar entre elementos relacionados — por exemplo, anunciando que um botão controla um painel específico e permitindo ao utilizador saltar para ele.

Quando o id referenciado em aria-controls não existe no documento, a relação fica quebrada. Os leitores de ecrã podem tentar localizar o elemento alvo e falhar silenciosamente, ou podem anunciar uma relação de controlo que não leva a lado nenhum. Isto degrada a experiência para utilizadores que dependem de tecnologia assistiva e viola a especificação WAI-ARIA, que exige que o valor de aria-controls seja uma lista de referências de ID válidas apontando para elementos no mesmo documento.

Causas comuns deste erro incluem:

• Erros de digitação no id ou no valor aria-controls.
• Conteúdo gerado dinamicamente onde o elemento controlado ainda não foi renderizado ou foi removido do DOM.
• Erros de copiar-colar onde aria-controls foi copiado de outro componente, mas o id correspondente não foi atualizado.
• Referência a elementos em iframes ou shadow DOM, que são considerados contextos de documento separados.

O atributo aria-controls aceita uma ou mais referências de ID separadas por espaços. Cada ID listado deve corresponder a um elemento no mesmo documento.

Como corrigir

1. Verifique se o elemento alvo existe no documento e tem exatamente o id que aria-controls referencia.
2. Verifique erros de digitação — a correspondência de ID é sensível a maiúsculas e minúsculas, portanto mainPanel e mainpanel não são iguais.
3. Se o elemento controlado for adicionado dinamicamente, certifique-se de que está presente no DOM antes ou ao mesmo tempo que o elemento de controlo, ou atualize aria-controls programaticamente quando o alvo ficar disponível.
4. Se o elemento controlado estiver genuinamente ausente (ex.: renderizado condicionalmente), remova o atributo aria-controls até que o elemento alvo exista.

Exemplos

Incorreto: aria-controls referencia um ID inexistente

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

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

Isto desencadeia o erro porque aria-controls="info-panel" não corresponde ao id real de "infopanel" (note o hífen em falta).

Correto: aria-controls corresponde ao ID de um 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>

Correto: relação entre separador e painel de separador

<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 os valores de aria-controls — tab1-panel e tab2-panel — correspondem corretamente a elementos presentes no documento.

Correto: barra de deslocamento personalizada controlando uma região

<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>

Correto: controlando múltiplos elementos

O atributo aria-controls pode referenciar múltiplos IDs separados por espaços. Cada ID deve existir no 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>

Saiba mais:

W3C Reference

W3C WAI ARIA 1.2 aria-controls

→