Popover

Overlay ancorado para conteúdo interativo inline — date pickers, mini formulários, command bars.

Overview

Popover é um overlay ancorado a um trigger, aberto por clique (intencional) e capaz de hospedar conteúdo interativo — formulários compactos, date pickers, color pickers, command bars, share menus.

Use a tabela mental para escolher entre Popover, Tooltip e HoverCard:

Primitive	Trigger	Conteúdo	Tipico
Popover	clique	interativo	mini-form, date picker, settings
Tooltip	hover/focus	label curto	"Salvar (⌘S)"
HoverCard	hover	preview não-interativo	profile preview

Preview

Popover com mini formulário.

Anatomy

<Popover>
  <PopoverTrigger />
  <PopoverContent>
    <PopoverHeader>
      <PopoverTitle />
      <PopoverDescription />
    </PopoverHeader>
    {/* conteúdo interativo */}
  </PopoverContent>
</Popover>

Subcomponents

Componente	Descrição
`Popover`	Raiz controlando open/closed.
`PopoverTrigger`	Elemento que abre o popover ao clicar.
`PopoverContent`	Container portalado, com smart positioning.
`PopoverAnchor`	Elemento alternativo para ancoragem (raro).
`PopoverHeader`	Wrapper de título + descrição.
`PopoverTitle`	Título da seção (não obrigatório).
`PopoverDescription`	Descrição opcional.

Usage

import {
  Popover,
  PopoverTrigger,
  PopoverContent
} from "@kalvner/kds/overlays/popover";
import { Button } from "@kalvner/kds/forms/button";

export function FilterPopover() {
  return (
    <Popover>
      <PopoverTrigger asChild>
        <Button variant="outline">Filtros</Button>
      </PopoverTrigger>
      <PopoverContent>
        {/* form fields */}
      </PopoverContent>
    </Popover>
  );
}

Props

PopoverContent

Prop	Tipo	Default	Descrição
`align`	`'start' \| 'center' \| 'end'`	`'center'`	Alinhamento horizontal em relação ao trigger.
`side`	`'top' \| 'right' \| 'bottom' \| 'left'`	`'bottom'`	Lado preferido — Radix flipa se não couber.
`sideOffset`	`number`	`4`	Espaço entre trigger e content.

Composition

Icon trigger

Popover ancorado a um botão de ícone.

When to use

Date pickers, color pickers, mini-formulários (1–3 campos).
Settings inline (densidade, ordenação, exibição de colunas).
Share menu / convidar membro com email + role.
Command bar / quick actions.

When not to use

Para fluxos longos — use Sheet ou Dialog.
Para labels curtos não-interativos — use Tooltip.
Para previews não-interativos — use HoverCard.
Para listas de ações — use DropdownMenu.

Best practices

Largura controlada. O default é w-72. Para conteúdo mais largo, ajuste via className. Não deixe overflow horizontal.
Não aninhe. Popovers dentro de popovers atrapalham foco; use Sheet ou outra navegação se a hierarquia for funda.
Feche após confirmação. Em forms dentro de popover, fechar programaticamente após onSubmit confirma a operação visualmente.
Ancore ao trigger. PopoverAnchor existe para casos avançados, mas o padrão é deixar o trigger ser o âncora.

Accessibility

Concern	Comportamento
Roles	Radix Popover aplica `role="dialog"` (ou `aria-haspopup="dialog"` no trigger).
Foco	Foco entra no primeiro elemento focável dentro do content. Volta ao trigger ao fechar.
Keyboard	`Esc` fecha. `Tab` cicla. Diferente do AlertDialog, fechar por overlay click é permitido.
Screen reader	Quando há `PopoverTitle`, anuncia como nome. Sem título, aria-label do trigger é a referência.
Reduced motion	Animações respeitam `prefers-reduced-motion`.

Tooltip — labels curtos não-interativos.
HoverCard — previews não-interativos via hover.
DropdownMenu — listas de ações.
Dialog — para fluxos focados e bloqueantes.

Popover

On this page