Combobox acessível do zero: implementando o padrão WAI-ARIA na mão

Um combobox com autocomplete em HTML↳HTML45 conteúdosA importância do HTML e CSS para quem trabalha com UI Design e Design SystemProduto & UX · dez 2024Como hostear seu site HTML gratuitamente com GitHub PagesDev (Back & Front) · jun 2025SQL Server – Como criar um versionamento de código das suas Stored Procedures em HTML e com comentários da alteraçãoData · nov 2020Ver tudo em Dev (Back & Front) → e JS puro, seguindo o APG passo a passo, com teclado, aria-activedescendant e teste real em leitor de tela.

O problema não é o autocomplete bonito. O problema é o usuário de leitor de tela que digita duas letras, ouve nada, aperta seta pra baixo e o NVDA anuncia "em branco". Isso acontece todo dia em produto brasileiro que puxou um de uma UI lib sem entender o contrato ARIA por trás. Quando o componente quebra numa atualização ou você precisa customizar, ninguém sabe consertar porque ninguém sabe o que deveria estar acontecendo.

A melhor cura pra isso é montar um na mão pelo menos uma vez, seguindo o Combobox Pattern do WAI-ARIA Authoring Practices Guide. Vou construir aqui o caso mais comum: editable combobox com list autocomplete e seleção manual (o que o APG chama de aria-autocomplete="list" com manual selection). O usuário digita, a lista filtra, ele escolhe ou fica com o que digitou.

O contrato que o APG define

Antes de código, os três estados que precisam estar corretos, senão nada funciona no leitor de tela:

O detalhe que mais gente erra: o foco do DOM nunca sai do input. A navegação com setas dentro da lista é feita movendo o aria-activedescendant, não dando focus() nas opções. É o padrão de foco virtual que o APG chama de "managing focus using aria-activedescendant". As opções não entram no Tab e não recebem tabindex.

Passo 1: a estrutura HTML

<label id="cb-label" for="cb-input">Cidade</label>
<div class="combo">
  <input
    id="cb-input"
    role="combobox"
    type="text"
    aria-autocomplete="list"
    aria-expanded="false"
    aria-controls="cb-listbox"
    aria-labelledby="cb-label"
    autocomplete="off" />
  <ul id="cb-listbox" role="listbox" aria-labelledby="cb-label" hidden></ul>
</div>

Um ponto de acessibilidade↳Acessibilidade11 conteúdosO que é Acessibilidade Web e como tornar seu site mais acessívelDev (Back & Front) · mar 2019Design para veteranos digitais: acessibilidade para nós mesmosProduto & UX · jan 2020Dicas de Front-End para usabilidade, acessibilidade, performance e responsividadeProduto & UX · fev 2025Ver tudo em Produto & UX → que já cabe aqui: autocomplete="off" no input evita que o autofill nativo do navegador brigue com a nossa lista, sobrepondo duas UIs. E o aria-labelledby no input e na listbox garante que ambos herdam o nome "Cidade" (WCAG 4.1.2, nome acessível é parte da definição de pronto).

Passo 2: renderizar e filtrar as opções

const DADOS = ['Belo Horizonte', 'Belém', 'Brasília', 'Curitiba',
               'Fortaleza', 'Recife', 'Salvador', 'São Paulo'];

const input = document.getElementById('cb-input');
const listbox = document.getElementById('cb-listbox');
let ativo = -1; // índice da opção ativa; -1 = nenhuma

function filtrar(texto) {
  const q = texto.trim().toLowerCase();
  return q === '' ? DADOS
    : DADOS.filter(d => d.toLowerCase().includes(q));
}

function render(opcoes) {
  listbox.innerHTML = '';
  opcoes.forEach((valor, i) => {
    const li = document.createElement('li');
    li.id = `cb-opt-${i}`;
    li.role = 'option';
    li.textContent = valor;
    li.setAttribute('aria-selected', 'false');
    li.addEventListener('click', () => selecionar(i));
    listbox.appendChild(li);
  });
}

Note que cada

Passo 3: abrir, fechar e mover o foco virtual

function abrir() {
  if (listbox.children.length === 0) return;
  listbox.hidden = false;
  input.setAttribute('aria-expanded', 'true');
}

function fechar() {
  listbox.hidden = true;
  input.setAttribute('aria-expanded', 'false');
  input.removeAttribute('aria-activedescendant');
  ativo = -1;
}

function moverAtivo(indice) {
  const opcoes = [...listbox.children];
  if (ativo > -1) opcoes[ativo].setAttribute('aria-selected', 'false');
  ativo = indice;
  if (ativo > -1) {
    const li = opcoes[ativo];
    li.setAttribute('aria-selected', 'true');
    input.setAttribute('aria-activedescendant', li.id);
    li.scrollIntoView({ block: 'nearest' });
  } else {
    input.removeAttribute('aria-activedescendant');
  }
}

O scrollIntoView({ block: 'nearest' }) resolve um bug clássico: como o foco do DOM não se move, a lista não rola sozinha quando você desce além da área visível. Sem essa linha, o usuário de teclado (não só de leitor de tela) perde a opção ativa da tela.

Passo 4: o teclado, exatamente como o APG manda

input.addEventListener('input', () => {
  render(filtrar(input.value));
  if (input.value && listbox.children.length) abrir();
  else fechar();
});

input.addEventListener('keydown', (e) => {
  const total = listbox.children.length;
  switch (e.key) {
    case 'ArrowDown':
      e.preventDefault();
      if (listbox.hidden) { render(filtrar(input.value)); abrir(); }
      moverAtivo(ativo + 1 >= total ? 0 : ativo + 1);
      break;
    case 'ArrowUp':
      e.preventDefault();
      if (listbox.hidden) { render(filtrar(input.value)); abrir(); }
      moverAtivo(ativo <= 0 ? total - 1 : ativo - 1);
      break;
    case 'Enter':
      if (ativo > -1) { e.preventDefault(); selecionar(ativo); }
      break;
    case 'Escape':
      fechar();
      break;
    case 'Home':
    case 'End':
      // deixa o navegador mover o cursor no texto: NÃO capturar
      break;
  }
});

function selecionar(i) {
  input.value = listbox.children[i].textContent;
  fechar();
  input.focus();
}

Aqui mora o aviso mais importante do próprio APG, em caixa alta na fonte:

IMPORTANT: Ensure JavaScript does not interfere with browser-provided text editing functions by capturing key events for the keys used to perform them.

WAI-ARIA Authoring Practices Guide, Combobox Pattern

Por isso eu não dei preventDefault() no Home/End: num campo editável, essas teclas movem o cursor no texto e isso é comportamento do navegador que a gente não deve sequestrar. Só chamo preventDefault() nas setas verticais (para não mover o cursor enquanto navego a lista) e no Enter (para não submeter o form).

O tropeço que eu não esperava: role como propriedade

No passo 2 escrevi li.role = 'option'. Isso funciona em navegadores atuais (a propriedade IDL role reflete o atributo), mas se você tem que suportar algo mais antigo, o silêncio é traiçoeiro: a

Outro susto: se você esquecer de remover o aria-activedescendant ao fechar a lista, o NVDA continua tentando anunciar uma opção que não está mais visível. Por isso o fechar() faz removeAttribute.

Como verificar que deu certo

Nota da redação: o código desta seção não foi executado em ambiente real. Valide antes de usar em produção. Além disso, a sugestão de usar uma região role="status" para anunciar a contagem de resultados é uma recomendação do autor, não uma prescrição literal do APG, e as observações sobre comportamento de NVDA e VoiceOver descrevem a experiência pessoal do autor, não dados de uso verificados.

Teste de teclado não substitui teste com leitor de tela, mas é o primeiro filtro:

1. Tab entra no input e só nele (as opções não recebem foco).
2. Digite "be", seta pra baixo: a primeira opção fica destacada e aria-activedescendant aponta pro id dela (veja no DevTools).
3. Escape fecha sem apagar o que você digitou.
4. Enter numa opção preenche o campo e fecha.

Depois, o teste que realmente conta:

• NVDA + Firefox no Windows (NVDA é um leitor de tela gratuito): ao subir/descer a lista, você deve ouvir o texto da opção seguido de "1 de 5". Ao digitar, o número de resultados deveria ser anunciado, o que pede um aria-live extra. O APG não trata desse ponto especificamente; na minha leitura, uma forma razoável de resolver isso é usar uma região role="status" anunciando algo como "5 resultados disponíveis", mas isso é sugestão minha, não recomendação da fonte.
• VoiceOver + Safari no macOS: confirme que o nome "Cidade" é falado ao focar o campo e que "combobox, recolhido/expandido" é anunciado conforme o aria-expanded muda.

Se o leitor de tela anuncia o campo como "edição de texto" e nunca fala "combobox", o role="combobox" não chegou na árvore de acessibilidade, volte pro passo 1.

O que fica em aberto

Essa implementação cobre list autocomplete com seleção manual. As outras variantes do APG (inline autocomplete com completion string destacada, automatic selection, popup em grid ou date picker) mudam o teclado e a semântica. E há a parte que nenhum tutorial resolve por você: anunciar a contagem de resultados via live region sem tagarelar a cada tecla, coisa que exige debounce e é onde muita UI lib peca. Mas o ponto do exercício não é substituir a lib, é entender o contrato bem o bastante para saber, quando ela quebrar, exatamente onde olhar.

Fonte: W3C WAI-ARIA Authoring Practices Guide — Combobox Pattern