Popover API do HTML: playground ao vivo e referência
Playground da Popover API do HTML
Popover API do HTML: popovertarget, showPopover, eventos | We.Inc
Teste a Popover API ao vivo: popovers auto, manual e hint, botões popovertarget, showPopover, hidePopover e togglePopover, além de um log dos eventos beforetoggle e toggle.
Adicione o atributo popover a qualquer elemento e aponte um botão para ele com popovertarget="id", e o navegador cuida de abrir, fechar, da top layer e da tecla Escape para você, sem JavaScript. Em scripts, chame showPopover(), hidePopover() ou togglePopover() e escute os eventos beforetoggle e toggle. popover="auto" fecha quando você clica fora; manual não fecha.
Tipos de popover
Valor
Clicar fora ou Escape fecha
Outros popovers
popover ou popover="auto"
Sim
Abrir um fecha os outros popovers auto, exceto os seus ancestrais
popover="manual"
Não, você mesmo fecha
Qualquer quantidade pode ficar aberta ao mesmo tempo
popover="hint"
Sim
Fecha outros popovers hint que não são seus ancestrais; feito para tooltips
Popovers costumavam exigir uma biblioteca de posicionamento, um handler para cliques fora e uma briga com z-index. A Popover API leva tudo isso para o HTML. O playground abaixo cria um popover real no seu navegador para você trocar o tipo, controlá-lo por código e ver os eventos disparando em ordem.
Escolha auto, manual ou hint para o popover no playground.
Abra com o botão declarativo ou chame os três métodos com os botões de script.
Clique fora ou pressione Escape para ver quais tipos fecham sozinhos.
Leia o log de eventos: beforetoggle dispara primeiro, depois toggle, cada um com oldState e newState.
Só elementos button e input podem ter popovertarget. Use um botão de verdade para que quem usa o teclado consiga alcançá-lo.
popovertargetaction aceita toggle (o padrão), show ou hide, então botões separados de abrir e fechar não precisam de script.
Estilize o estado aberto com :popover-open e escureça a página por trás com ::backdrop.
Um popover não é modal. Para um formulário que precisa ser concluído antes de voltar à página, use um dialog aberto com showModal().
Popovers visíveis ficam na top layer, então você não precisa mais de um z-index alto para mantê-los acima de tudo.
Perguntas frequentes
Quais navegadores suportam a Popover API?
O MDN marca a Popover API como Baseline recém-disponível desde janeiro de 2025, o que significa que ela funciona nas versões mais recentes dos principais navegadores. Algumas partes mais novas, como o valor hint, podem ter suporte mais restrito, então confira a tabela de compatibilidade antes de depender delas.
Qual é a diferença entre popovers auto e manual?
Um popover auto tem light dismiss: clicar fora dele ou pressionar Escape o fecha, e abri-lo fecha os outros popovers auto. Um popover manual fica aberto até que um botão ou script o feche, e vários podem ficar abertos juntos, o que é bom para toasts.
O Escape fecha todos os popovers?
O Escape fecha popovers auto e hint, os mesmos que fecham com um clique fora. Um popover manual ignora os dois, então precisa de um botão de fechar próprio ou de uma chamada a hidePopover().
Como saber quando um popover abre ou fecha?
Escute o evento toggle no elemento do popover. O newState dele é "open" ou "closed". O evento beforetoggle dispara logo antes da mudança, e é o lugar certo para preparar o conteúdo.
Onde um popover aparece por padrão?
No centro do viewport, com posicionamento fixo, na top layer. Mova-o com o seu próprio CSS, ou com anchor positioning onde o navegador suportar.
Declarativo primeiro
A maioria dos popovers não precisa de script nenhum. O botão e o popover são ligados pelo id, e o navegador cuida da alternância, do light dismiss e da tecla Escape.
Recorra a showPopover() e seus irmãos quando o gatilho não é um botão, como abrir uma dica depois de uma validação de formulário que falhou ou fechar um toast com um timer.
Menus, toasts e dicas
Auto combina com menus e seletores que devem sumir quando a atenção vai para outro lugar. Manual combina com notificações que se empilham e ficam até serem dispensadas. Hint é pensado para tooltips de hover e foco.
Seja qual for o tipo, mantenha o conteúdo curto e garanta que toda ação dentro dele também possa ser feita pelo teclado.
Referência da Popover API
Atributos, métodos, eventos e seletores
Nome
Tipo
O que faz
Atributo global
Transforma o elemento em popover: auto, manual ou hint
Atributo em button ou input
Id do popover que o controle abre e fecha
Atributo em button ou input
toggle (padrão), show ou hide
showPopover()
Método
Adiciona o popover à top layer
hidePopover()
Método
Remove da top layer e oculta
togglePopover()
Método
Mostra se estiver oculto, oculta se estiver visível
Evento
Dispara antes da mudança de estado; tem oldState e newState
Evento
Dispara depois da mudança de estado; tem oldState e newState
:popover-open
Pseudoclasse CSS
Corresponde a um popover enquanto ele está visível
::backdrop
Pseudoelemento CSS
A camada atrás de um popover visível
Exemplos de popover sem JavaScript
Estes frames rodam com os scripts desativados, e os popovers continuam funcionando, porque o comportamento vem do HTML.
Um menu com popover auto
Clique no botão e depois clique em outro lugar ou pressione Escape. O menu se fecha sozinho.
Um toast manual com botões separados de mostrar e ocultar
Clicar fora não faz nada aqui. Só o botão de ocultar fecha o toast.
Escurecer a página atrás de um popover
::backdrop estiliza a camada sob o popover. Ele continua não sendo modal; dá para clicar na página por trás para fechá-lo.
Controlando um popover com JavaScript
Métodos, eventos e detecção de suporte
Verifique o suporte antes de chamar os métodos e depois leia newState no evento toggle.
Playground de popover
Seu navegador roda um popover real aqui: troque o tipo, chame os métodos e leia o log de eventos.
Botão declarativo (popovertarget)
Métodos via script
Eu sou um popover {v}. Clique fora ou pressione Escape para testar o light dismiss.
Fechar
Estado: {v}
Log de eventos
Limpar log
Nenhum evento ainda.
Este navegador não suporta a Popover API, então o playground está desativado.