A API Popover

A API de sobreposições oferece ao HTML uma maneira nativa de criar sobreposições, caixas de diálogo, dicas de ferramenta e menus — sem JavaScript manual para posicionamento, gerenciamento do foco, dispensa ao clicar fora ou fechamento com Escape. O comportamento integrado corresponde ao que os usuários esperam.

Adicione popover a qualquer elemento para transformá-lo em uma sobreposição. Por padrão, ele fica oculto. Um botão de acionamento com popovertarget="popover-id" o exibe ao ser clicado. O navegador gerencia automaticamente o estado de abertura e fechamento.

popover="auto", o padrão — fecha ao clicar fora ou pressionar Escape; apenas uma sobreposição automática pode ficar aberta por vez. popover="manual" — não fecha automaticamente; precisa ser fechada explicitamente por JS ou por outro acionador.

O atributo popovertarget vincula um botão a uma sobreposição por meio do id. O navegador gerencia o comportamento de alternância: clique no botão para exibir, clique novamente ou clique fora para dispensar. Não são necessários manipuladores de eventos para o uso básico.

As sobreposições são renderizadas na camada superior — acima de todo o restante do conteúdo, independentemente do índice ou do contexto de empilhamento. Isso elimina o problema clássico de um modal oculto atrás de um elemento pai que esconde o conteúdo excedente, um erro comum em sobreposições feitas manualmente.

JavaScript pode exibir ou ocultar sobreposições: element.showPopover(), element.hidePopover(), element.togglePopover(). A semântica é a mesma do acionador declarativo — a dispensa ao clicar fora continua funcionando no modo automático.

As sobreposições disparam um evento toggle quando seu estado muda. O newState do evento é "open" ou "closed". Isso é útil para análises, gerenciamento do foco ou coordenação de outros elementos da interface com o estado aberto da sobreposição.

A pseudoclasse :popover-open corresponde às sobreposições em estado aberto. Estilize transições, opacidade e transformações com base nesse estado: [popover]:popover-open { opacity: 1; transform: none; }.

Combinadas com a API de posicionamento por âncora do CSS, as sobreposições podem ser posicionadas automaticamente em relação ao acionador — sem necessidade de JavaScript para o padrão clássico de uma dica de ferramenta próxima ao botão. Ambos os recursos fazem parte da mesma iniciativa moderna de primitivas de interface.

O navegador confina o foco em sobreposições modais, restaura o foco no acionador ao fechar e anuncia o estado aberto da sobreposição aos leitores de tela. Criar isso manualmente exige uma quantidade significativa de código repetitivo com ARIA; a API de sobreposições oferece tudo isso gratuitamente.

Chrome e Safari oferecem suporte à API de sobreposições; o Firefox adicionou suporte mais recentemente. Para obter compatibilidade mais ampla, existe uma pequena solução de compatibilidade. Projetos novos podem usar a implementação nativa e aprimorar progressivamente a experiência em navegadores mais antigos.

Muitas bibliotecas de modais em JS, como sweetalert e react-modal, existem principalmente para contornar o que a API de sobreposições agora faz nativamente. Planeje a migração: pacotes menores, padrões melhores e menos código para manter. A API de sobreposições é uma das maiores melhorias do HTML em anos.

O que popover="auto" faz que popover="manual" não faz?

A API de sobreposições adiciona o atributo popover, além de showPopover/hidePopover/togglePopover em JS, vinculação de acionadores com popovertarget, renderização na camada superior acima de todos os contextos de empilhamento, a pseudoclasse :popover-open e eventos toggle. O modo automático fecha ao clicar fora; o modo manual exige uma ação explícita. Ela substitui a maioria das bibliotecas personalizadas de modais e dicas de ferramenta por uma primitiva HTML que gerencia corretamente acessibilidade, foco e posicionamento.