ts
| Guidance | Practices |
|---|---|
| Do | Use for interactive content such as menus, pickers, forms, and command panels that need focus management. |
| Do | Prefer the Popover component for standard trigger-content pairs; use the hook for custom trigger patterns. |
| Don't | Use for non-interactive hover previews: use useHoverCard or useTooltip instead. |
| Param | Type | Description |
|---|---|---|
onShow | () => void | Callback fired when the popover becomes visible. |
onHide | () => void | Callback fired when the popover is hidden. Use this to return focus to the trigger when needed. |
xstyle | StyleXStyles | StyleX styles applied to the popover content wrapper, after the default surface styles. |
hasLightDismiss | boolean (default: true) | Whether clicking outside dismisses the popover. |
hasAutoFocus | boolean (default: true) | Whether to automatically focus the first focusable element when opened. |
hasCloseButton | boolean (default: true) | Whether to include a hidden close button that appears for keyboard users. |
closeButtonLabel | string (default: 'Close popover') | Accessible label for the hidden close button. |
dialogLabel | string | Accessible label for the popover dialog. Provide one when there is no visible title. |
hasSurface | boolean (default: true) | Whether to apply the default popover surface background, radius, and shadow. |
| Field | Type | Description |
|---|---|---|
| triggerRef | (el: HTMLElement | null) => void | Ref callback to attach to the trigger element for CSS anchor positioning. |
| contentRef | RefObject<HTMLDivElement | null> | Ref for the popover content container used by focus trapping. |
| anchorId | string | CSS anchor name for advanced positioning cases. |
| show | (options?: {skipAutoFocus?: boolean}) => void | Imperatively show the popover. skipAutoFocus preserves current focus for input-triggered popovers. |
| hide | () => void | Imperatively hide the popover. |
| toggle | () => void | Toggle the popover open or closed. |
| isOpen | boolean | Whether the popover is currently open. |
| id | string | Unique ID for aria-describedby or aria-controls. |
| render | (children: ReactNode, props?: ContextRenderProps) => ReactNode | Render function for anchor-positioned popover content. Pass placement and alignment here. |
| triggerProps | {aria-haspopup: "dialog"; aria-expanded: boolean; aria-controls: string} | ARIA attributes to spread onto the trigger element. |