Primitiveoverlay

Popover

Stable

Superfície ancorada e não modal, com header, título e descrição. Composto sobre Base UI Popover. A diferença para o Dialog é a proteção: aqui a página atrás continua viva e a superfície pode ser abandonada com um clique fora, então uma decisão que precisa ser concluída antes de seguir pertence ao Dialog. A diferença para o Tooltip é que aqui cabe o cursor.

Instalação

npx up-web-ds add popover

Preview

Default

With Form

Sides

With Content List

All states

Default

With Form

Sides

With Content List

Usage

Imports de Popover

import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from '@/components/ui/popover'
import { Button } from '@/components/ui/button'

Popover

1
2
3
4
5
6
7
8
9
10
11
12
13
14<Popover>
  <PopoverTrigger render={<Button variant="outline" />}>
    Sobre a distribuição
  </PopoverTrigger>
  <PopoverContent>
    <PopoverHeader>
      <PopoverTitle>Distribuição interna</PopoverTitle>
      <PopoverDescription>
        Este item é publicado pelo registry de consumo e instalado por{' '}
        <code className="font-mono type-caption">up-web-ds add</code>.
      </PopoverDescription>
    </PopoverHeader>
  </PopoverContent>
</Popover>

Props

Popover

Props de Popover
Prop	Type	Default	Description
actionsRef	`React.RefObject<PopoverRootActions \| null>`	sem valor padrão	A ref to imperative actions. - `unmount`: Manually unmounts the popover. Call this after any externally controlled closing animation finishes. - `close`: Closes the popover imperatively when called.
children	`React.ReactNode \| PayloadChildRenderFunction<unknown>`	sem valor padrão	The content of the popover. This can be a regular React node or a render function that receives the `payload` of the active trigger.
defaultOpen	`boolean`	`false`	Whether the popover is initially open. To render a controlled popover, use the `open` prop instead.
defaultTriggerId	`string \| null`	sem valor padrão	ID of the trigger that the popover is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open popover.
handle	`PopoverHandle<unknown>`	sem valor padrão	A handle to associate the popover with a trigger. If specified, allows external triggers to control the popover's open state.
modal	`boolean \| "trap-focus"`	`false`	Determines if the popover enters a modal state when open. - `true`: user interaction is limited to the popover: document page scroll is locked, and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. - `'trap-focus'`: focus is trapped inside the popover, but document page scroll is not locked and pointer interactions outside of it remain enabled. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior. When `modal` is `true`, focus trapping is enabled only if `<Popover.Close>` is rendered inside `<Popover.Popup>`. It can be visually hidden with your own CSS if needed, such as Tailwind's `sr-only` utility. When `modal` is `'trap-focus'`, render `<Popover.Close>` inside `<Popover.Popup>` so touch screen readers can escape the popup.
onOpenChange	`((open: boolean, eventDetails: PopoverRoot.ChangeEventDetails) => void)`	sem valor padrão	Event handler called when the popover is opened or closed.
onOpenChangeComplete	`((open: boolean) => void)`	sem valor padrão	Event handler called after any animations complete when the popover is opened or closed.
open	`boolean`	sem valor padrão	Whether the popover is currently open.
triggerId	`string \| null`	sem valor padrão	ID of the trigger that the popover is associated with. This is useful in conjunction with the `open` prop to create a controlled popover. There's no need to specify this prop when the popover is uncontrolled (that is, when the `open` prop is not set).

Estende PopoverPrimitive.Root.Props.

PopoverTrigger

Props de PopoverTrigger
Prop	Type	Default	Description
className	`string \| ((state: PopoverTriggerState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
closeDelay	`number`	`0`	How long to wait before closing the popover that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
delay	`number`	`300`	How long to wait before the popover may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
handle	`PopoverHandle<unknown>`	sem valor padrão	A handle to associate the trigger with a popover.
nativeButton	`boolean`	`true`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (e.g. `<div>`).
openOnHover	`boolean`	`false`	Whether the popover should also open when the trigger is hovered.
payload	`unknown`	sem valor padrão	A payload to pass to the popover when it is opened.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, PopoverTriggerState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: PopoverTriggerState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende PopoverPrimitive.Trigger.Props. Aceita também os atributos padrão de um elemento React (285 não listados).

PopoverContent

Props de PopoverContent
Prop	Type	Default	Description
align	`Align`	`'center'`	How to align the popup relative to the specified side.
alignOffset	`number \| OffsetFunction`	`0`	Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.
className	`string \| ((state: PopoverPopupState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
finalFocus	`boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => void \| boolean \| HTMLElement \| null)`	sem valor padrão	Determines the element to focus when the popover is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
initialFocus	`boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => void \| boolean \| HTMLElement \| null)`	sem valor padrão	Determines the element to focus when the popover is opened. By default, focus moves to the first tabbable element inside the popup, except when the popover is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (first tabbable element or popup). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, PopoverPopupState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
side	`Side`	`'bottom'`	Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
sideOffset	`number \| OffsetFunction`	`6`	Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.
style	`React.CSSProperties \| ((state: PopoverPopupState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende PopoverPrimitive.Popup.Props & Pick< PopoverPrimitive.Positioner.Props, 'align' | 'alignOffset' | 'side' | 'sideOffset' >. Aceita também os atributos padrão de um elemento React (275 não listados).

PopoverTitle

Props de PopoverTitle
Prop	Type	Default	Description
className	`string \| ((state: PopoverTitleState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, PopoverTitleState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: PopoverTitleState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende PopoverPrimitive.Title.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

PopoverDescription

Props de PopoverDescription
Prop	Type	Default	Description
className	`string \| ((state: PopoverDescriptionState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, PopoverDescriptionState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: PopoverDescriptionState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende PopoverPrimitive.Description.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

PopoverClose

Props de PopoverClose
Prop	Type	Default	Description
className	`string \| ((state: PopoverCloseState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
nativeButton	`boolean`	`true`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, PopoverCloseState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: PopoverCloseState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende PopoverPrimitive.Close.Props. Aceita também os atributos padrão de um elemento React (285 não listados).

Composition

Gatilho e conteúdo são irmãos. O header é opcional e existe para dar nome acessível ao popup.

Composição de Popover

Popover

PopoverTrigger
PopoverContent
- PopoverHeader
  - PopoverTitle
  - PopoverDescription
- PopoverClose

Metadata

Notas de acessibilidade

Teclado verificado por teste: Enter abre a partir do gatilho, o foco entra na superfície e pousa no primeiro controle, Tab percorre os demais, e Escape fecha devolvendo o foco ao gatilho — o mesmo acontece no fechamento explícito e no clique fora. Leitor de tela verificado por teste: o popup tem papel dialog nomeado pelo PopoverTitle e descrito pelo PopoverDescription, e aria-expanded no gatilho acompanha o estado real. Touch verificado em navegador com emulação de toque em viewport de 375px: gatilho e controles internos medem acima do mínimo de 24x24 da WCAG 2.2 SC 2.5.8, a superfície é limitada a calc(100vw-2rem) e o toque fora fecha. Reduced motion verificado com prefers-reduced-motion: reduce — o zoom e o deslizamento por lado são aplicados em motion-safe:, então sob reduce o painel aparece no lugar sem viajar; o animate-in e o fade ficam, porque é o animationend deles que fecha o ciclo de montagem.

Classificação

Layer: Primitive
Domínio: Domain-free (compartilhado)
Categoria: overlay
Status: Stable

Origem e distribuição

Fonte: shadcn registry / popover
Licença: MIT
URL: https://ui.shadcn.com/r/styles/base-vega/popover.json
Distribuição: Interna

Acessibilidade

Teclado: revisado
Leitor de tela: revisado
Touch: revisado
Reduced motion: revisado

Dependências

Pacotes: @base-ui/react
Ícones: Nenhum
Construído sobre: Nenhum
Usado por: Roadmap Calendar