Popover
Balão (popover) — um painel pequeno que abre ao lado de um botão e guarda conteúdo interativo, como um formulário curto, algumas configurações ou links. Ele não bloqueia a página; para um rótulo simples, use um tooltip.
modal
Instalação
Configure o Camaleo uma vez (Instalação) e importe o que precisar. Ele renderiza no cliente.
import { Popover, PopoverTrigger, PopoverContent, PopoverTitle, PopoverDescription, PopoverClose } from "@camaleo/react";Anatomia
O PopoverContent é renderizado num portal, com o estilo, o modo e a cor da página em volta do gatilho. Ele abre embaixo do gatilho, alinhado ao início dele (mude com side e align), e vai para o outro lado quando não há espaço. A seta está sempre lá. O seu conteúdo fica dentro do popover-scroll, então ponha o layout (grid, gap) num wrapper seu ou nesse slot, não no PopoverContent.
popover-positioner <div> · num portal
popover-popup <div> · role=dialog
popover-arrow <div> · aponta para o gatilho
popover-scroll <div> · rola quando passa da altura da tela
popover-title <h2> · dá nome ao diálogo
popover-description <p> · opcional
popover-close <button> · opcional
Exemplos
Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima. Todos começam fechados: abra e teste Tab, Escape e um clique fora.
relatorio-3tri.pdf
Um formulário curto
Clique em Renomear. O initialFocus põe o cursor no campo, Enter salva, e o foco volta para o botão enquanto uma mensagem de status confirma o novo nome.
Controlado
Com open e onOpenChange você sabe quando ele fecha. Aqui isso marca as notificações como lidas e avisa.
A partir de um botão de ícone
O botão de ícone precisa de aria-label; o PopoverTitle dá nome ao painel. O leitor de tela avisa que ele abre um diálogo e se está expandido.
Com botão de fechar
Celular não tem tecla Escape. Um PopoverClose com um × visível dá a todo mundo um jeito de sair.
const total = items.reduce((sum, item) => sum + item.price,0,);
Configurações que valem na hora
A página continua visível e usável atrás do popover, então as mudanças aparecem na hora, sem botão Aplicar.
Foco preso dentro
Normalmente o Tab sai do popover e fecha ele. Com modal="trap-focus", o Tab dá a volta por dentro, e o que já foi digitado não se perde.
Em contexto
São pedaços inteiros de interface para copiar, no estilo que você escolheu.
Relatório do 3º tri
Compartilhar um documentoPopover · Switch · Field · Input · Button
| Cliente | Data | Total |
|---|---|---|
| Padaria Estrela | 14/03/2026 | R$ 2.060,00 |
| Café Aurora | 13/03/2026 | R$ 432,50 |
| Mercado Bom Dia | 11/03/2026 | R$ 6.200,00 |
Colunas da tabelaPopover · CheckboxGroup · Table
Enviar as faturas de março
12 clientes · prazo 31/03/2026
Adiar um lembreteCard · Popover · RadioGroup · Badge
Boas práticas
FaçaLista de comandos é um menu.
O Menu traz setas, busca pela primeira letra e os papéis certos para Editar, Duplicar e Excluir.
EviteUm popover cheio de botões.
Cada um vira uma parada do Tab, e o leitor de tela anuncia um diálogo em vez de um menu.
FaçaUm tooltip para um nome.
Passar o mouse ou dar foco mostra "Arquivar" na hora, e é o mesmo texto que o leitor de tela fala.
EviteUm clique para ler um rótulo.
Se ele só explica o botão, ninguém deveria precisar abrir e fechar um painel. Popover é para conteúdo com que a pessoa interage.
Props
PropriedadeTipoPadrãoDescrição
defaultOpenbooleanfalseSe o popover começa aberto, sem controle pelo código.
openboolean—Se o popover está aberto. Use junto com
onOpenChange para controlar pelo código.onOpenChange(open, eventDetails) => void—Chamado quando o popover abre ou fecha, com o motivo em
eventDetails.modal"trap-focus" | booleanfalse
true prende o foco, trava a rolagem e bloqueia cliques fora. "trap-focus" só prende o foco. O padrão é false.O PopoverContent aceita side, align e as props do popup, incluindo initialFocus e finalFocus. O PopoverTrigger aceita openOnHover e delay para um painel que também abre com o mouse por cima; mantenha o clique, para funcionar no toque e no teclado.
Styling hooks
Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio popup.
Atributos
data-sidebottom · top · left · right
data-alignstart · center · end
data-open · data-closedno popup
data-starting-style · data-ending-styleenquanto aparece e some
Tokens que ele lê
Cor
--cml-border--cml-fg--cml-fg-muted--cml-focus-offset--cml-focus-ring--cml-focus-width--cml-popover-bg--cml-popover-border--cml-shadow-popover--cml-surface-raised
Forma e tamanho
--cml-border-width--cml-popover-border-width--cml-radius-control--cml-radius-popover
Tipografia e movimento
--cml-duration-fast--cml-ease-standard--cml-font-display--cml-font-weight-display--cml-motion-scale
Só deste componente
--cml-corner-shape--cml-item-highlight
/* um painel mais largo para o popover de compartilhar */
.share [data-slot="popover-popup"] {
inline-size: min(26rem, calc(100vw - 2rem));
}Acessibilidade
EnterNo gatilho, abre o popover e leva o foco para o primeiro controle, para o initialFocus, ou para o painel quando ele não tem controles.
TabPassa pelos controles. Depois do último, o foco vai para o que vem depois do gatilho e o popover fecha.
Shift + TabDo primeiro controle, volta para o gatilho; o popover continua aberto.
EscapeFecha o popover e devolve o foco ao gatilho.
- Ele nunca passa do espaço na tela: daí em diante, o conteúdo rola dentro dele e a seta fica no lugar. Só com texto dentro, a caixa que rola vira uma parada de Tab para quem usa teclado conseguir rolar.
- É um diálogo não modal: o resto da página continua alcançável. Um clique fora fecha o popover.
- O gatilho tem aria-haspopup="dialog" e aria-expanded, então o leitor de tela sabe o que abre e se está aberto.
- O PopoverTitle dá nome ao diálogo. Coloque um mesmo quando o painel é pequeno.
- O resultado de uma ação feita nele vai numa mensagem de status: o popover fecha e leva o texto junto.
Relacionados
TooltipUm rótulo curto no hover ou no foco, nunca interativo.MenuUma lista de comandos navegável pelas setas.DrawerUm painel maior que vem da borda, para tarefas mais longas.
Esta página foi útil? · Editar esta página no GitHub