children | React.ReactNode
({ close, open, toggle, id }) => React.ReactNode | (optional) Alternative content property. Accepts nodes or a render function that receives the same helpers as content. |
content | React.ReactNode
({ close, open, toggle, id }) => React.ReactNode | (optional) Content rendered inside the popover. Can also be a render function that receives helpers such as close. |
title | React.ReactNode | (optional) Optional heading shown above the body content. Matches the typography used in TermDefinition. |
trigger | React.ReactNode
({ active, ref, toggle, open, close }) => React.ReactNode | (optional) Custom trigger element or render function. Required unless you point Popover at an existing element using targetElement / targetSelector. |
triggerProps | React.HTMLAttributes<HTMLElement> | (optional) Props forwarded to the default trigger wrapper (e.g. aria-*). |
triggerAttributes | React.HTMLAttributes<HTMLElement> | (deprecated) Deprecated. Use triggerProps instead. |
triggerClassName | string | (optional) Class name merged with the default trigger wrapper. |
triggerOffset | number | (optional) Spacing in pixels between the trigger element and the popover surface. |
targetRefreshKey | unknown | (optional) Forces the popover to recalculate its layout whenever this value changes. Useful when the trigger moves but the DOM tree stays mounted. |
targetElement | HTMLElement
React.RefObject<HTMLElement>
{ horizontalRef?: HTMLElement | React.RefObject<HTMLElement>; verticalRef?: HTMLElement | React.RefObject<HTMLElement> } | (optional) Existing DOM element (or ref) used instead of a rendered trigger. Provide { horizontalRef, verticalRef } when horizontal and vertical anchors differ. |
targetSelector | string | (optional) CSS selector pointing to an element in the document to use as the trigger target. |
horizontalOffset | number | (optional) Horizontal offset in pixels to adjust the popover placement. Positive values move the popover to the right, negative values move it to the left. Useful for fine-tuning alignment when the default placement needs adjustment. |
arrowEdgeOffset | number | (optional) Offset in pixels from the edge when the arrow is positioned at the edge. When set, this value replaces the default edge spacing (8px) and arrow boundary (8px). Useful for components like Tooltip that need the arrow closer to the edge. |
openInitially | boolean | (optional) Whether the popover should be open by default when uncontrolled. |
open | boolean | (optional) Controls the open state when provided. Use together with onOpenChange. |
placement | "top"
"right"
"bottom"
"left" | (optional) Preferred placement of the popover relative to the trigger. |
alignOnTarget | "left"
"center"
"right"
null | (optional) Adjust horizontal alignment of the popover body when placement is top/bottom; ignored for other placements. |
arrowPosition | "center"
"top"
"right"
"bottom"
"left" | (optional) Align the arrow along the axis of the selected placement (e.g., left/right for placement="right"). |
arrowPositionSelector | string | (optional) CSS selector that points to the element the arrow should align with. When the popover points vertically it aligns horizontally, and vice versa for horizontal placements. |
hideArrow | boolean | (optional) Hide the arrow element from the popover. When true, the arrow will not be rendered regardless of the arrowPosition property. |
hideCloseButton | boolean | (optional) Removes the built-in close button. |
focusOnOpen | boolean | (optional) If true, focus is moved into the popover content when it opens. |
focusOnOpenElement | HTMLElement
() => HTMLElement | (optional) Provide a specific element (or function returning one) to receive focus when the popover opens. |
restoreFocus | boolean | (optional) Moves focus back to the trigger or the element focused when the popover opened. Defaults to true. Outside clicks and taps preserve focus at the interaction target. |
restoreFocusTo | HTMLElement
React.RefObject<HTMLElement>
() => HTMLElement | (optional) Provide a specific element, ref or function returning an element to receive focus when the popover closes. Takes precedence over the trigger and previously focused element. |
preventClose | boolean | (optional) Prevent closing the popover when interacting outside of it or pressing Escape. Useful when the popover needs to stay open while other parts of the page are interacted with. |
showDelay | number | (optional) Delay (ms) before the popover becomes active. Useful for hover-triggered popovers. |
hideDelay | number | (optional) Delay (ms) before the popover starts hiding. Defaults to 0. |
noInnerSpace | boolean | (optional) Remove the default padding inside the popover by setting --inner-space: 0 on the surface. |
closeButtonProps | Partial<ButtonProps> | (optional) Customize the built-in close button (icon, title, variant, etc.). |
skipPortal | boolean | (optional) Render inline instead of inside the shared Popover portal. |
portalRootClass | string | (optional) Extra className applied to the portal wrapper (only when not using skipPortal). |
keepInDOM | boolean | (optional) Keep the portal mounted in the DOM even when the popover is closed. Useful when the content should preserve its state. |
noAnimation | boolean | (optional) Disable show/hide animations. |
fixedPosition | boolean | (optional) Use fixed positioning so the popover follows the viewport instead of the page scroll. |
autoAlignMode | "initial"
"scroll"
"never" | (optional) Control when the popover automatically flips its placement to fit within the viewport. initial (default): Flip placement only on initial open when there's limited space. scroll: Flip placement on initial open and during scroll events. never: Never automatically flip placement, always use the specified placement property. |
autoAlignViewportThreshold | number | (optional) Bias vertical auto alignment toward the preferred placement until the trigger crosses a viewport threshold. Only applies to placement="top" and placement="bottom". Example: 0.75 keeps placement="bottom" until the trigger reaches the bottom quarter of the viewport. |
contentRef | React.RefObject<HTMLSpanElement> | (optional) Ref forwarded to the popover content element. |
noMaxWidth | boolean | (optional) If set to true, the popover will not have a max-width limitation. |
omitDescribedBy | boolean | (optional) Skips adding aria-describedby on the trigger when you handle accessibility yourself. |