Pular para o conteúdo
Sobreposição

Popover

/componentes/popover.mdmarkdown cru, para quem lê com agent em vez de olho

Painel

Importar
import { Popover } from '@rivocode/ui'

Quando usar

Painel ancorado de conteúdo livre. A peça entre o Tooltip, que só mostra texto curto, e o Dialog, que rouba a tela inteira.

Compõe com PopoverTrigger, PopoverContent, PopoverTitle, PopoverDescription e PopoverClose.

side, align e sideOffset ficam no PopoverContent: quem escreve a tela pensa neles junto com o conteúdo.

Quando não usar

Dica curta de um botão só de ícone é Tooltip: só texto, sem nada clicável. Prévia que abre ao pousar num link é PreviewCard, que não pede clique. O Popover abre no clique e pode levar ação dentro.

Lista de ações é Menu, que traz a navegação por seta e a semântica de menu. Confirmação colada no botão é Popconfirm. E tarefa que precisa da tela inteira é Dialog; no celular, o painel grande vai em Sheet.

No React Native

Não porta. O painel ancorado ao gatilho é um problema de tela estreita antes de ser um problema de toque: ele nasce debaixo do dedo que o abriu e não tem para onde fugir. No React Native o equivalente é o Sheet, que sobe de baixo e não disputa espaço com nada.

API

PropTipoPadrão
actionsRef0.4.0

Uma ref para as ações imperativas.

RefObject<PopoverRootActions | null>sem padrão
defaultOpen0.4.0

Se o popover começa aberto.

booleanfalse
defaultTriggerId0.4.0

ID do gatilho ao qual o popover está associado.

string | nullsem padrão
handle0.4.0

Um elo para associar o popover a um gatilho.

PopoverHandle<Payload>sem padrão
modal0.4.0

Se o popover aberto fica em estado modal.

"trap-focus" | booleanfalse
onOpenChange0.4.0

Chamado quando o popover abre ou fecha.

((open: boolean, eventDetails: PopoverRootChangeEventDetails) => void)sem padrão
onOpenChangeComplete0.4.0

Chamado depois que as animações terminam, quando o popover abre ou fecha.

((open: boolean) => void)sem padrão
open0.4.0

Se o popover está aberto agora.

booleansem padrão
triggerId0.4.0

ID do gatilho ao qual o popover está associado.

string | nullsem padrão

Partes

Popover se monta com estas peças. Todas vivem nesta página, porque separar cada uma num endereço obrigaria a abrir seis abas para montar uma tela.

PopoverClose

/popover-close.md

Fecha o painel de dentro dele, sem você guardar estado.

O painel já fecha com Esc e com clique fora; este serve para o botão que conclui (o Aplicar de um filtro, o Entendi de uma explicação) fechar junto com o que ele faz.

PropTipoPadrão
nativeButton0.4.0

Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`.

booleantrue
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, PopoverCloseState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

PopoverContent

/popover-content.md

O painel, em portal no contêiner do RivoProvider.

side, align e sideOffset moram aqui de propósito: quem escreve a tela decide o lado junto com o conteúdo, e não na raiz, longe do que vai dentro. O painel vira sozinho quando não cabe do lado pedido.

São as mesmas três props, com o mesmo significado e a mesma folga padrão de 6px, no MenuContent, no SelectContent, no ComboboxContent e no TooltipContent: o que flutua nesta biblioteca também se posiciona igual.

Ancorar em outro elemento

anchor troca o gatilho por outro ponto de apoio: um elemento, uma ref, um retângulo virtual ou uma função que devolve um deles. É o caminho do detalhe que abre colado num item que não é botão de abrir painel, como a tarja do EventCalendar:

<Popover open={open} onOpenChange={setOpen}>
  <PopoverContent anchor={tarja} finalFocus={() => tarja ?? true}>
    <PopoverTitle>Consulta das 9h</PopoverTitle>
  </PopoverContent>
</Popover>

Sem PopoverTrigger, o Popover é controlado, e o finalFocus diz para onde o foco volta ao fechar: sem ele, cai no body.

PropTipo
align0.4.0

Alinhamento no eixo do lado escolhido.

Align
anchor

Onde o painel se ancora, no lugar do gatilho: um elemento, uma ref para ele, um retangulo virtual ou uma funcao que devolve um deles.

ElementRefObject<Element | null>VirtualElement(() => Element | VirtualElement | null)null
finalFocus0.4.0

O elemento que recebe o foco quando o popover fecha.

booleanRefObject<HTMLElement | null>((closeType: InteractionType) => void | boolean | HTMLElement | null)
initialFocus0.4.0

O elemento que recebe o foco quando o popover abre.

booleanRefObject<HTMLElement | null>((openType: InteractionType) => void | boolean | HTMLElement | null)
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, PopoverPopupState> | ReactElement<unknown, string | JSXElementConstructor<any>>
side0.4.0

Lado preferido do gatilho.

Side
sideOffset0.4.0

Distancia entre o gatilho e o painel, em pixels.

number | OffsetFunction

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

PopoverDescription

/popover-description.md

O texto do painel, ligado a ele por aria-describedby.

PropTipo
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, PopoverDescriptionState> | ReactElement<unknown, string | JSXElementConstructor<any>>

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

PopoverTitle

/popover-title.md

O título do painel, ligado a ele por aria-labelledby.

Sem ele o leitor de tela abre um painel sem nome, e quem navega por teclado descobre onde está lendo o primeiro parágrafo.

PropTipo
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, PopoverTitleState> | ReactElement<unknown, string | JSXElementConstructor<any>>

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

PopoverTrigger

/popover-trigger.md

O que abre o painel, e a âncora dele.

A posição é medida a partir daqui, então o gatilho é o elemento visível ao lado do qual o painel deve aparecer, e não um invólucro maior que o empurraria para longe. Com openOnHover, abre na passagem do mouse; use com parcimônia, porque painel que abre sozinho atravessa o caminho de quem só estava passando.

Ele não tem pele própria (o uso comum é render={<Button />}, e duas fontes de estilo brigariam), mas tem o anel de foco do teclado. Foco não é pele: quando o gatilho é escrito à mão, o anel daqui é o único que existe.

PropTipoPadrão
closeDelay0.4.0

Quanto esperar antes de fechar o popover aberto pelo passar do ponteiro.

number0
delay0.4.0

Quanto esperar antes de o popover poder abrir pelo passar do ponteiro.

number300
handle0.4.0

Um elo para associar o gatilho a um popover.

PopoverHandle<unknown>sem padrão
nativeButton0.4.0

Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`.

booleantrue
openOnHover0.4.0

Se o popover abre também quando o ponteiro passa sobre o gatilho.

booleanfalse
payload0.4.0

Um dado a entregar ao popover quando ele abre.

unknownsem padrão
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, PopoverTriggerState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.