useAnchoredPopover

Manages positioned popovers anchored to a reference element using Floating UI. For simple popovers that don’t need positioning, see usePopover.

import { useAnchoredPopover } from '@volvo-cars/react-headless';

const MyComponent = () => {
  const { anchorProps, popoverProps, togglePopover } = useAnchoredPopover({
    placement: 'bottom-start',
  });

  return (
    <div>
      <button onClick={togglePopover} {...anchorProps}>
        Open popover
      </button>
      <div className="popover p-16 shadow-sm" {...popoverProps}>
        Popover content
      </div>
    </div>
  );
};

Placement

The placement option controls where the popover appears relative to the anchor. Available placements: 'top', 'top-start', 'top-end', 'bottom', 'bottom-start' (default), 'bottom-end', 'left', 'left-start', 'left-end', 'right', 'right-start', 'right-end'.

import { useAnchoredPopover } from '@volvo-cars/react-headless';

function Example() {
  const { anchorProps, popoverProps, togglePopover } = useAnchoredPopover({
    placement: 'top-end',
  });

  return (
    <div>
      <button onClick={togglePopover} {...anchorProps}>
        Open above
      </button>
      <div {...popoverProps}>Content</div>
    </div>
  );
}

With arrow

Enable an arrow pointing from the popover to the anchor element by setting withArrow. Spread popoverArrowProps on a child element inside the popover.

import { useAnchoredPopover } from '@volvo-cars/react-headless';

function Example() {
  const { anchorProps, popoverProps, popoverArrowProps, togglePopover } =
    useAnchoredPopover({
      placement: 'bottom',
      withArrow: true,
    });

  return (
    <div>
      <button onClick={togglePopover} {...anchorProps}>
        Open popover
      </button>
      <div {...popoverProps}>
        <div {...popoverArrowProps} />
        Content
      </div>
    </div>
  );
}

API

Options

useAnchoredPopover accepts an options object with the following properties:

• placement — where to position the popover relative to the anchor: 'top', 'bottom', 'left', 'right', and their -start/-end variants (default: 'bottom-start')
• behaviour — popover behaviour mode: 'auto' (default), 'manual', or 'hint'
• withArrow — enables an arrow element pointing to the reference (default: false)
• onToggle — callback triggered on the popover ToggleEvent

Returns

The hook returns an object with:

• isOpen — whether the popover is currently open
• togglePopover — function to toggle the popover state
• showPopover — function to open the popover
• hidePopover — function to close the popover
• anchorProps — props to spread on the anchor/trigger element
• popoverProps — props to spread on the popover element (includes positioning styles)
• popoverArrowProps — props to spread on the arrow element (when withArrow is enabled)
• elements — references to the anchor and popover DOM elements