Popover API - novas possibilidades para tooltips nativos do navegador

• A Popover API substitui, com recursos nativos do navegador, os event listeners em JavaScript, o gerenciamento de estado e a sincronização manual de atributos ARIA que eram indispensáveis nas implementações tradicionais de tooltips
• Apenas com os atributos popover e popovertarget, abrir/fechar, tratamento da tecla Esc e navegação por teclado funcionam automaticamente
• Melhora a previsibilidade para leitores de tela, sincroniza aria-expanded automaticamente e elimina categorias inteiras de bugs de acessibilidade, como restauração de foco
• Em algumas áreas, como controle de timing e detecção de intenção de hover, JavaScript ainda é necessário, mas o modelo principal de interação fica a cargo do navegador
• Em sistemas de design grandes ou em casos que exigem posicionamento complexo, bibliotecas ainda fazem sentido, mas o padrão está migrando para APIs nativas

---

Problemas dos tooltips tradicionais

• Antes da Popover API, o navegador não tinha um conceito nativo de tooltip que funcionasse de forma abrangente com mouse, teclado e tecnologias assistivas
• Repetia-se sempre o mesmo padrão: elemento gatilho, elemento de tooltip oculto e JavaScript para coordenar os dois
• Na aparência era simples, mas ao colocar em produção para usuários reais surgiam vários problemas
  • Usuários de teclado entravam no gatilho com Tab, mas o tooltip não aparecia
  • O leitor de tela lia duas vezes ou simplesmente não lia
  • Ao mover o mouse rapidamente, ocorria flicker
  • Em telas pequenas, o conteúdo se sobrepunha
  • Não fechava com a tecla Esc, e o foco se perdia
• Com o tempo, o código crescia com acúmulo de event listeners, tratamento separado para hover/focus, casos especiais de clique externo e sincronização manual de atributos ARIA

Por que bibliotecas eram usadas

• Bibliotecas faziam o trabalho real de posicionamento, flipping nos limites da viewport, coordenação de eventos por tipo de entrada e percepção de rolagem em layouts complexos
• Só o posicionamento já justificava dependências, porque lidar com contêineres roláveis, transforms e layouts responsivos é complexo
• O problema de verdade surgia no comportamento de acessibilidade
  • O tooltip aparecia tarde demais ou nem aparecia
  • Em navegação rápida por tabulação, o tooltip era ignorado
  • O fechamento com Esc era instável
• Usuários de mouse esperam imediatismo, enquanto usuários de teclado esperam previsibilidade, e dar suporte aos dois criava atrasos e edge cases
• Em leitores de tela, o tooltip podia ser lido, não ser lido ou ser lido duas vezes, gerando comportamento inconsistente
• Se um único atributo ARIA deixasse de ser atualizado manualmente, isso já podia causar confusão ou estados invisíveis na árvore de acessibilidade

O problema não era o código em si, e sim os limites da plataforma

• A implementação era testada e as bibliotecas eram robustas, mas o problema central era a falta de affordances apropriadas na plataforma web
• O navegador não tinha como reconhecer que aquele elemento era um tooltip; tudo se baseava em convenções com elementos genéricos, event listeners, ARIA manual e lógica customizada de dismiss
• Com o tempo, pequenas mudanças traziam risco, e ajustes triviais causavam regressões em uma estrutura frágil
• Ao adicionar um novo tooltip, a mesma complexidade era herdada integralmente

Primeira adoção da Popover API

• A motivação da migração não foi uma nova experiência, mas o cansaço de manter comportamentos de tooltip que o navegador já deveria entender
• A tentativa começou na forma mais simples: <button popovertarget="tip-1"> + <div id="tip-1" popover="manual" role="tooltip">
• Sem event listeners, sem rastreamento de estado, sem atualização de ARIA em JavaScript
• Ao focar o botão, o tooltip aparecia; ao pressionar Esc, desaparecia

Diferenças percebidas imediatamente

• Abrir/fechar sem JavaScript: o navegador lida com a invocação só com HTML, e a relação entre o gatilho e o tooltip fica explícita
• Tecla Esc automática: sem adicionar listeners de teclado, o navegador já entende a possibilidade de fechar o popover
• Sincronização automática de estado ARIA: o atributo aria-expanded é atualizado automaticamente ao abrir/fechar o popover, eliminando gerenciamento manual e o risco de estado obsoleto
• Mais importante do que a redução de código é a mudança de responsabilidade: antes, o JavaScript “fazia existir” o tooltip; agora, o navegador entende seu papel na marcação e o integra ao modelo de foco, à árvore de acessibilidade e às regras nativas de dismiss

Entendendo Invoker Commands

• popovertarget="id" conecta o botão ao elemento popover
• popovertargetaction define o comportamento
  • show: apenas abre
  • hide: apenas fecha
  • toggle (padrão): se estiver aberto, fecha; se estiver fechado, abre
• É possível ter múltiplos gatilhos para o mesmo tooltip, sem necessidade de JavaScript para a interação básica

Ganhos gratuitos de acessibilidade

• O teclado “simplesmente funciona”

  • Antes, era uma estrutura em várias camadas: foco tinha que acionar, blur tinha que ocultar, Esc precisava ser ligado manualmente e o timing ainda tinha que bater
  • Ao definir o atributo popover (auto ou manual), o navegador aplica o comportamento padrão: Tab/Shift+Tab funcionam normalmente e Esc fecha de forma confiável toda vez
  • Foram removidos do código handlers globais de keydown, lógica de limpeza específica para Esc e verificações de estado durante navegação por teclado

• Previsibilidade para leitores de tela

  • Foi a área com maior melhora: antes, mesmo com trabalho cuidadoso de ARIA, o comportamento variava e pequenas mudanças eram arriscadas
  • Com popover="manual" role="tooltip", o comportamento se tornou muito mais estável e previsível
  • Após a migração, o Lighthouse deixou de mostrar alertas sobre estados ARIA incorretos — porque esses estados ARIA customizados simplesmente deixaram de existir

• Gerenciamento de foco

  • Antes havia regras complexas: exibir com foco no gatilho, não fechar ao mover o foco para dentro do tooltip, tratar blur e restaurar foco manualmente
  • Com a Popover API, o foco se move naturalmente para o popover e, ao fechar, há restauração automática do foco para o gatilho
  • O código de restauração de foco não foi adicionado; foi removido

Onde a Popover API ainda fica aquém

• Timing do tooltip

  • O popover nativo abre e fecha imediatamente, então, se o mouse passar rápido demais pelo gatilho, o tooltip pode piscar e parecer instável
  • Ainda é necessário controle de delay entre hover/focus e abertura
  • O comportamento básico de abrir/fechar fica a cargo do navegador e dos HTML invoker commands; o JavaScript é usado apenas para refinar comportamentos intencionais, como cancelar o ocultamento quando o ponteiro se move para o tooltip
  • Esse campo também está sendo explorado em CSS, com trabalhos relacionados a interest/invoker caminhando para permitir expressar delays de entrada/saída diretamente em CSS

• Intenção de hover e Invoker Commands

  • O navegador não sabe por que alguém está fazendo hover sobre um elemento — não consegue determinar se foi intencional ou se o ponteiro só estava passando
  • Como os invoker commands já cuidam da abertura/fechamento principal, o JavaScript deixa de controlar o modelo de interação e passa apenas a adicionar intenção por cima
  • O JavaScript é usado apenas para comportamentos que o navegador não pode inferir, como um pequeno delay antes de ocultar ou cancelar o fechamento quando o ponteiro vai para o tooltip

• Manual Popover e foco

  • Com popover="manual", ao contrário do auto popover, o navegador não restaura o foco automaticamente
  • Se o tooltip abrir com foco e fechar com blur, é preciso devolver o foco explicitamente ao gatilho
  • Isso cria uma fronteira clara entre o comportamento da plataforma e a intenção do usuário

• Avaliação honesta

  • A Popover API não resolve magicamente os tooltips, mas faz parar o trabalho de reconstruir uma infraestrutura frágil
  • Ainda é preciso usar JavaScript e considerar edge cases, mas agora dá para focar em resolver problemas de produto em vez de recriar primitives de UI

Quando uma biblioteca de tooltip ainda é necessária

• Sistemas de design grandes ou maduros

  • Em sistemas de design grandes, usados por várias equipes, uma biblioteca continua sendo razoável para garantir comportamento centralizado, padrões documentados e defaults consistentes
  • Mudar o modelo de interação subjacente não é só uma decisão técnica, mas também uma decisão organizacional
  • Ela fornece guardrails para integrantes do time que não dominam as nuances de acessibilidade

• Requisitos complexos de posicionamento

  • Se for necessário detectar colisões entre contêineres de scroll aninhados, ter lógica customizada de flipping ou controle fino de offsets/limites, bibliotecas como Floating UI ainda levam vantagem
  • CSS anchor positioning já começa a cobrir boa parte desse problema — com CSS puro, passa a ser possível posicionar relativamente ao gatilho, considerar a viewport e fazer edge flipping
  • Ainda é um recurso novo e há issues conhecidos, mas ele faz parte do Interop, com perspectiva de suporte completo e consistente entre navegadores
  • Se você precisa de comportamento cross-browser consistente agora, a biblioteca ainda é a opção prática

• Equipes com pouca experiência em acessibilidade

  • Em equipes com pouco conhecimento de acessibilidade, uma boa biblioteca funciona como rede de segurança — não garante acessibilidade perfeita, mas evita erros comuns
  • A Popover API oferece defaults melhores, mas ainda é preciso saber quando adicionar role, labels, gerenciamento de foco e testes
  • Sem esse entendimento, até ferramentas nativas podem ser usadas de forma incorreta

Conclusão

• Com a Popover API, tooltip deixa de ser algo simulado e passa a ser um elemento que o navegador entende
• Abrir, fechar, comportamento de teclado, tratamento de Esc e boa parte da acessibilidade passam a ser fornecidos pela própria plataforma
• Em sistemas de design complexos, customização avançada ou restrições legadas, bibliotecas ainda continuam válidas, mas o padrão está mudando
• É a primeira vez em que o tooltip mais simples pode também ser o tooltip mais correto
• Se você substituir apenas um tooltip do produto pela Popover API, já dá para ver o que desaparece do código