usePopover
Popup positioning and behaviour built on floating-ui.
The hook behind Popover, Tooltip, ConfirmPopover, Select, and Search. It positions the popup relative to the trigger (flipping and shifting near the screen edge), closes it on an outside click and Escape, and returns props with handlers and ARIA attributes. Use it when you need a custom popup that the ready-made components do not cover. openOn picks how it opens: click, hover (including focus), or manual.
Usage
'use client';
import { usePopover } from '@prosazhin/pbcomponents';
function Example() {
const { open, refs, floatingStyles, getReferenceProps, getFloatingProps } = usePopover({
placement: 'bottom-start',
openOn: 'click',
role: 'dialog',
});
return (
<>
<button
ref={refs.setReference}
{...getReferenceProps()}
>
Filters
</button>
{open && (
<div
ref={refs.setFloating}
style={floatingStyles}
{...getFloatingProps()}
>
Popup content
</div>
)}
</>
);
}Hook API
Parameters
| Parameter | Type / variants | Purpose | Default |
|---|---|---|---|
open? | boolean | External open state. | — |
defaultOpen? | boolean | Initial internal state. | — |
onOpenChange? | (open: boolean) => void | Called when the popup opens or closes. | — |
placement? | PopoverPlacement | Side and alignment relative to the trigger. Defaults to bottom-start. | — |
openOn? | 'click' | 'hover' | 'manual' | What opens the popup. Defaults to click. | — |
hoverDelay? | number | Open delay with openOn: hover, in milliseconds. | — |
offset? | number | Distance from the trigger in pixels. Defaults to 6. | — |
matchTriggerWidth? | boolean | Makes the popup as wide as the trigger. | — |
arrowRef? | RefObject<Element | null> | Arrow ref used to position it. | — |
role? | 'dialog' | 'menu' | 'listbox' | 'tooltip' | ARIA role of the popup. | — |
disabled? | boolean | Disables opening. | — |
Returns
| Value | Type / variants | Purpose |
|---|---|---|
open | boolean | Whether the popup is open. |
setOpen | (open: boolean) => void | Opens or closes the popup. |
refs | { setReference, setFloating, … } | Ref callbacks for the trigger and the popup. |
context | FloatingContext | floating-ui context, for example for FloatingArrow. |
floatingStyles | CSSProperties | Positioning styles of the popup. |
side | 'top' | 'right' | 'bottom' | 'left' | Actual side after flipping. |
getReferenceProps | (props?) => Record<string, unknown> | Props for the trigger (handlers and ARIA). |
getFloatingProps | (props?) => Record<string, unknown> | Props for the popup. |